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PRIME'S BASIC/VM PROGRAMMER'S GUIDE (REV. 0, April 1979) 

This guide docixnents Prime BASIC/VM and the relevant FRIMOS operating 
system features as implemented at Master Disk Revision Level 16. 
Information appearing in the Rev. 14 IDR and PTU57 (Rev. 15) , has 
been corrected as necessary and incorporated into the text of this 
guide. 

This guide is organized to make life easier for you, the BASIC/VM 
application progranmer or casual user. 

Wfe assume you are familiar with BASIC in some form, and will easily 
adapt to Prime's implementation and extensions, which are fully defined 
in this guide. 

Most PRIME systan users will want to know something about our operating 
system, roiMOS. Deciding which of the many FRIMOS concepts are 
important in BASIC/VM programming is not an easy task. Therefore, this 
guide contains a suttmary of the most useful FRIMOS concepts, terns and 
commands. Should additional details be required to complete special 
prograiming tasks, we refer you to the appropriate PRIME documents m 
which supplanental information can be found. 

The result is a single docunent containing everything y^u need to know 
to write, modify, compile, execute, and debug most BASIC/VM application 
programs. 

We hope you will find this a helpful guide to the particulars of 
BASIC/VM prograitining within the FRIMOS operating system. We invite 
comments on the organization and ^lilosophy of this guide, as well as 
its contents, accuracy, and clarity. 
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SECTION 1 
INTRODUCTION TO BASIC/VM 

AUDIENCE 

This document has been prepared for the BASIC user or programmer Wio is 
not acquainted with Prime's BASIC/VM. It is recoitmended that those 
unfamiliar with any form of the BASIC language refer to a commercially 
available text. Fbr example: 

Marateck, Samuel, BASIC ; Academic Press, Inc. 

Waite and Mather, Editors, BASIC, Sixth Edition ; University Press 
of New England. 

This docunent defines the Prime BASIC/VM language and illustrates^ its 
major uses with many examples. In addition, it introduces Prime s 
operating systan, PRIMOS, and enables new users to access and use the 
system. 

EESCRIPTION OF BASIC/VM 

Prime's BASIC/VM, or virtual-memory BASIC, is a high level 
problenv-solving language useful in research, business, and educational 
facilities. Its simple and easily understood language structure makes 
it suitable for writing programs to handle both simple and conplicated 
mathematical problons. ll-ie language consists of systan commands vhich 
are directives to the BASIC/VM subsystem, and statanents, vhich are the 
fundamental components of programs. BASIC/VM programs are composed of 
nunbered statements and optional comments, vhich are notations to the 
user. 

BASIC/VM is a compiler for an extended form of the standard BASIC 
lar^uage. It is an upward compatible extension of Prime's BASIC 
Interpreter, employing the fast program execution and virtual memory 
capabilities of the Prime 350 and higher central processors. Programs 
previously written in interpretive BASIC will run under BASIC/VM 
without modification. 

The BASIC/VM Language Processor 

The components of the BASIC processor are: 

• BASIC Language Ccxnpiler 

• Command Processor 

• Statanent Editor 

The command processor interprets and executes all systan level 
directives. The larguage compiler translates program source code into 
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executable machine language. The statement editor enables complete 
modification of BASIC/VM programs on a line-by-line basis entirely 
within the BASICV system. 

Features 

pere are a nunber of features which distinguish EASIC/WI from other 
forms of the BASIC language. Thiese include: 

1. The ability to support multiple users without significant 
performance loss. 

2. It is compiled, rather than interpreted, for rapid program 
execution. 

3. The ability to run very large programs without compromising 
anall program efficiency. 

4. The ability to access MIDAS keyed- index files. 

5. Special methods of formatting output. 

6. Extensive alpjianuneric string support. 

7. Matrix manipulations. 

8. Multiple data segments and 128KB (64K word) procedure space. 

9. Immediate mode for instant calculations. 

10. An editor for complete program modification. 

11. A library of mathematical functions to aid in calculations. 

12. iRecursive function capability. 

13. Extended control functions (DO, DOEND, etc.) and statement 
modifiers (WHILE, UNTIL, UNLESS, FCR, IF) . 

14. Double-precision floating-point numeric data. 

HOW TO USE THIS MANUAL 

■niis manual has been organized to acccxtimodate several levels of user 
experience. if you know BASIC in some form and have used it on other 
systems but not Prime's, read Section 2 to familiarize yourself with 
Prime's operating system. A discussion of the terms and conventions 
aipearing in this manual is located in the first part of Section 2 
More information on Prime's embedded file management system (FMS)"* 
useful PRIM0S_ features (e.g., EDITOR), as weU as PRkoS-relatec^ 
terminology, is found in Appendix D. 
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If you have previously used a Prime computer and do not need a review 
of system access and file manipulation, proceed to Section 3, which 
describes the important canmands and concepts you need to work with 
BASIC/VM. It might be helpful to familiarize yourself with the 
conventions and terms in Section 2, however. 

A capsule summary of the BASIC/VM language elements, including a 
complete list of commands and statements, is found in Section 4. 
Programmers v*io have previously used a Prime system and/or Prime's 
Interpretive BASIC may need only Section 4 to get started. 

Basic programming information, including details on program control 
structure, data transfer, file handling, editing and debugging a 
program, is discussed in Sections 5 through 8. Section 9 deals with 
matrix and array manipulations. Section 10 contains a library of all 
nuneric and string system functions and describes how to define and 
implanent user-defined functions. Sections 11 through 15 canprise a 
complete reference to the BASIC/VM language, including nimeric and 
string data, commands and statements. 

The Appendices contain run-time error messages, ASCII character set 
list, glossary of PRIMOS concepts and terms, an overview of useful 
PRIMOS features, (e.g. EDITOR, Command Files), and sample programs. 

Conpatibility with Other Forms of BASIC 

While Prime BASIC/VM is generally compatible with other versions of 
BASIC, users should be aware of the following restrictions and 
alternative impl orientation features: 

• The ability to enter several statements on one line is not 
supported. 

• There is no 'BYE' command. 'QUIT' is its equivalent in 
BASIC/VM. 

• No lov«rcase input is accepted on command lines. 

• The double-quote character is not accepted by BASIC/VM as a 
delimiter as it is the default miMOS erase character .(See 
Section 2, Conventions.) Single quotes are used as 
delimiters, e.g., "This is OK'. 

• Prime's BASIC supports the use of statement modifiers like 
WHILE, UNTIL, UNLESS with statements like IF, J^INT and 
FOR-NEXT loops. 

• Prime's BASIC/VM supports double-precision floating-point 
numeric data. 

• The assignment statement LET is optional in BASIC/VM. 
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EASICAM has control features like two-branch deciders, 
e.g., IE'. ..THEN. ...ELSE, and logical loop control via the 
modifiers WHILE, m>ITIL, UNLESS, which allow the writing of 
structured language. 



REV. 1 - 



PDR3058 OVERVIEW CF FRIMOS 

SECTION 2 
OVERVIEW OF miMOS 



INTRODUCTION TO PRIM06 



Tills section introduces Prime's operating system, FRIMOS, and its most 
commonly used comnands. All users of BASIC/VM will need sane of the 
information here to access the systan and work with files. The 
ranainder of the information is necessary to acconplish more advanced 
programming tasks. Users new to Prime' s systan are referred to the 
glossary of terms in Appendix D. 



Additional information on all the subjects discussed in this section 
may be found in the following Prime docunents: 

New User's Guide Tb Editor And Runoff 

FRIMOS Progranmer's Conpanion 

Reference Guide, PRIMOS Commands 

Subroutine Reference Guide 
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COMVENTIOfB 

The conventions for FRIMOS commands are: 



• WORDS-IN-UPPER-CASE 

Capital letters identify command WDrds or keywords. They are to be 
entered literally. If a portion of an upper-case word is underlined, 
the underlined letters indicate the minimum legal abbreviation. 

• Words-in-lower-case 

Lower case letters identify parameters. The user substitutes an 
appropriate numerical or text value. 

• Braces { } 

Braces indicate a choice of parameters and/or keywords. Ifriless the 
braces are enclosed by brackets, at least one choice must be selected. 

• Brackets [ ] 

Brackets indicate that the word or parameter enclosed is optional. 

• Hyphen - 

A hyphen identifies a ccxnmand line option, as in: STOOL -LIST 

• Parentheses ( ) 

When parentheses appear in a command format, they must be included 
literally. 

• Ellipsis ... 

The preceding parameter may be repeated. 

• Angle brackets < > 

Used literally to separate the elements of a pathname. For exanple: 
<FOREST>BEBCH>BRANCH537 >'IWIG43 >LEAF4. 

• opt ion 

The word option indicates one or more keywords or parameters can be 
given, and thit a list of options for the particular canmand follows. 

• Spaces 

Command words, arguments and paraneters are separated in command lines 
by one or more spaces . In order to contain a literal space, a 
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parameter must be enclosed in single quotes. For example, a pathnane 
may contain a directory having a password: 

'<FOREST>BEBCH SECRET>BRANCH6 ' . 

The quotes ensure that the pathname is not interpreted as two items 
separated by a space. 

SMICIAL TERMINAL KEYS 
• CONTROL 

The key labeled CONTROL (or CTRL) changes the meaning of alphabetic 
keys. Holding down CONTROL vhile pressing an alphabetic key generates 
a Control Character. Control characters do not print. Some of than 
have special meanings to the conputer. Others are ignored. 



• RETURN 

The RETURN key ends a line. PRIMOS edits the line according to any 
Erase (") or Kill (?) characters, and either processes the line as a 
miMCG command, or passes it to a utility such as the editor. RETURN 
is also called CR or CARRIAGE-RETURN. 

• BREAK 

See CONTROL-P. 
Special Characters 

• Caret C) 

Used in EDITOR to enter octal numbers and for literal insertion of 
Erase and Kill characters. On sane terminals and printers, prints as 
up-arrow (t) • 

• Backslash (\) 

Default EDITOR tab character. 

• Double-quote (") 

Default erase character for miMOS, EDITOR, and RUNOFF Command Mode. 
Each double-quote erases a character fran the current line. Erasure is 
from right (the most recent character) to left. TWo double quotes 
erase two characters, three erase three, and so forth. You cannot 
erase beyond the beginning of a line. The miMOS command TERM (See 
Appendix D of this guide) allows the user to choose a different erase 
character. 
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• Saestion mark (?) 

Default kill character for FRIMOS, EDITOR, and RUNOFF Command Mode. 
Each question mark deletes all previous characters on the line. The 
raiMOB command TERM (Pppendix D of this guide) allows the user to 
choose a different kill character. 

• COMTROL-P 

QUIT immediately (interrupt/ terminate) from execution of current 
canmand and return to PRIMOS level. Bshoes as QUIT. Used to escape 
from undesired processes. Will leave used files open in certain 
circunstances. Equivalent to hitting BREAK key. 

• UNDERSCORE (J 

On some devices, prints as a backarrow (<-) . 
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SYSTEM PROMPTS 

The OK Prompt 

The OK prompt indicates that the most recent command to PRIMOS has been 
successfully executed, and that miMOS is ready to accept another 
command from the user. 



PRIi^OG supports type-ahead . The user need not wait for the "OK," after 
one command before beginning to type the next command. Hov\ever, since 
each character echoes as the user types it, output fran the previous 
command may appear on the terminal to be jumbled with the command being 
typed ahead. Type ahead is limited to 192 characters. 



The ERl Prompt 

The ERl prompt indicates that HRIMOG was unable to execute the most 
recent command, for one reason or another, and that PRIMOS is ready to 
accept another command from the user. The ER! prompt usually is 
preceded by one or more error messages indicating what PRIMOS thought 
the trouble was. 

CoTimon errors include: 

• Typographical errors 

• emitting a passwDrd 

• Being in the wrong directory 

• Forgetting a parameter or argiment 



USING THE FILE SYSTEM 

File and Directory Structures 

A roiMOS file is an organized collection of information identified by a 
filename. The file contents may represent a source program, an object 
program, a run-time memory image, a set of data, a program listing, 
text of an on-line document, or anything the user can define and 
express in the available symbols. 

Files are normally stored on the disks attached to the computer system. 
No detailed knowledge of the physical location of a file is required 
because the user, through FRIMOS commands, refers to files by name. On 
some systems, files may also be stored on magnetic tape for backup or 
for archiving. 

PRIMOS maintains a separate user file directory (UFD) for each user to 
avoid conflicts that might arise in assigrment of filenames. A master 
file directory (MFD) is maintained by PRIMOS for each logical disk 
connected to the systan. The MFD contains information about the 
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location of each User File Directory (UFD) on the disk. In turn, each 
UFD contains information about the location and content of each file or 
sub-UFD in that directory. 

The types of files most often encountered are shown in "rable 2-1. For 
a primer on the HRIMOS file system and a description of the ordering of 
information within files, refer to the Subroutine Fteference Guide. 

Directory Structure 

The PRIMOS file directory system is arranged as a tree. At the root 
are the disk volumes (also called partitions, or logical disks). Each 
disk volume has a Master File Directory (MFD) containing the names of 
User File Directories (UFDs) . Each UFD may contain not only files, but 
subdirectories (sub-UFDs) , and they may contain subdirectories as well. 
Directories may have subdirectories to any reasonable level. 

Pathnames 

A pathname (also called a tree sname) is a name used to specify uniquely 
any particular file or directory within PRIMOS. It consists of the 
nanes of the disk volume, the UFD, a chain of subdirectories, and the 
target file or directory. For example, 

<F0REST>BEECH>BRANCH5>SQUIRREL 

specifies a file on the disk volume FOREST, under the UFD BEECH and the 
sub-UFD BRANCH5. The file's nime is SQUIRREL. Figure 2-1 illustrates 
how pathnames show paths throucjh a tree of directories and files. 

Disk volume names, and the associated logical disk numbers, may be 
found with the STATUS DISKS command, described later. A pathname can 
be made with the logical disk number, instead of the disk volume name. 
For example, if FOREST is mounted as logical disk 3, 

<3 >BEECH>BRANCH5 >SQUIRREL 

specifies the same file as the previous exanple. 

Usually each UFD name is unique throughout all the logical disks. In 
our exanple that vould mean that there would be only one UFD n^amed 
BEBCH in all the logical disks, through 17. When that is the case, 
the volume or logical disk name may be omitted, and PRIMOS will search 
all the logical disks, startinci from 0, until the UFD is found. For 
example, if there is no UFD named BEECH on disks 0, 1, or 2, then 

BEECH>BRANCH5>SQUIRREL 

will specify the same file as the previous twD examples. This last 
form of pathname, in vhich the disk specifier is omitted, is called an 
ordinary pathname because it is very frequently used. 
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Table 2-1. 
Types of Files in FRIMOS 



File 
Type 



ASCII, 
uncompress- 
ed 



ASCII, 
Compressed 



Object 
(Binary) 



Saved 

Memory 

Image 

Segmented 
runfile 

Segmented 
data file 



UFD 
Sub-UFD 

MFD 



Disk record 
availabil- 
ity table 
DBKRAT file 

BOOT 



CMDNC0 



Created 



Programs 

SCBT 

COMOUTPUT 



CMPRES 
Some COBOL 
programs, ED 



Translators :RPG, 
FTN, PMA, COBOL, 
Binary Editor 

LCftD 

Applications 

programs 

SEG 



SGDR$$ 
subroutine 
MIDAS, IBMS 

CREATE 



MAKE 



MAKE 



How 
Accessed 



MAKE 



MAKE 



Programs 

ED (examine only) 

SLIST 

SPOOL 

FTN READ/WRITE 

EXPAND to ASCII 
SPOOLer with 
EXPAND option 
ED 

LOAD or SEG 
Binary Editor 
(Em) 

TAP, PSD 
Control panel 



SEG, VPSD 
Control panel 

SGDR$$ subroutine 

MIDAS 

DBMS 

Contents: LISTF 



Contents: LISTF 



How 
Deleted 



EELETE 
FOTIL IXLETE 



Use 



NO 



NO 



Contents: LISTF 



DELETE 
FUriL DELETE 



DELETE 
FUriL DELETE 
Binary Editor 

DELETE 
FUTIL DELETE 



SEG DELETE 
FUTIL TREEEL 

FUTIL TREDEL 
MIDAS KIDEEL 



raiLETE 
FUTIL TREDEL 

NO 



NO 



NO 



NO 



Source files, 
text , data 
records for 
sequential 
access 

Same as un- 
compressed 
ASCII 



Input to 
SEG or LCftD, 
Libraries 

Runf iles 



Runfiles 



Data records 
for direct 
access 

Used by 
FRIMOS 

Used by 
PRIMOS 

Used by 
PRIMOS 



Used by 
PRIMOS 

Used by 
PRIMOS 
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PINE1 



PINE2 



BEECH 



PINE3 



ELM 



(Not all the UFDs 
are shown.) 



This directory Is the MFD of 
the disk volume ''FOREST>. 



L 







-• 






-* 


ORIOLE 




-- 



This directory is the 
UFD ELM. 



This is the 
file ORIOLE. 



£ 



LEAF3 




-*■ 


LEAFS 










LEAF5 




-*■ 






-»- 






-•> 






-»► 



This is the 

subdirectory 

TWIG37. 



(Not all subdirectories 
and files are shown.) 



" 










-► 






-^ 


TREEHOUSE 










BRANCH5 




-^ 



This directory is 

theUFDBEECh 



r: 



TWIG14 



SQUIRREL 



TWIG37 



This is the 

subdirectory BRANCH 5. 



This is the 

file TREEHOUSE. 



r 



This is the 

file SQUIRREL. 



LEAF1 



LEAF3 



LEAF4 



This is the 

subdirectory 

TWIG14 



This is the 
file LEAFS. 



This is the 
file LEAF4. 



I'athnamos iidentifv files in a tree-structureiJ file system. The pathnames; 

<l-OREST>HEECIl>BRANCH5>SQUIRREL 

<FOREST>BEECH>BRANCH5>TWIG37>LEAI-8 

are illustrated. 



Figure 2-1. Examples of Files and Directories 

in PRIMOS Tree-structured File Systsn. 
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Pathnames vs. Filenames 

Most commands accept a pathname to specify a file or a directory; the 
terms "filename" and "pathname" maybe used almost interchangeably. A 
few commands, however, require a filename, not a pathname. It's easy 
to tell a filename frm a pathname. A pathname always contains a ">" , 
while a filename or directory name never does. 



Hone vs . Current Directories 

PRIMOS has the ability to remember twD working directories for each 
user: the "home" directory, and the "current" directory. With few 
exceptions, the home and current directories are the same. All work 
can be acconplished vAiile treating than both under the single concept 
of "working directory" . 

When the user logs in to a UFD, that UFD becomes the working directory. 
The ATTACH canmand changes the working directory to any other directory 
to which the user has access rights. A working directory may be an 
MFD, UFD, or sub-UFD. 

The ATTACH command has a home-key option v^hich allows the current 
directory to change viiile the hone directory remains the sane. See 
Reference Guide, PRIMOS Commands for details of this operation. 

Relative pathnames 

It is often more convenient to specify a file or directory pathname 
relative to the home directory, rather than via a UFD. For example, 
v*ien the home directory is 

BEECH>BRANCH5 
the commands 

OK, SLIST BEECH>BRANCH5>'MIG9>LEAF3 
and 

OK, SLIST *>'IWIG9>LEAF3 

have the same meaning. The synbol "*" as the first directory in a 
pathname means "hone directory". 



Current disk 

Occasionally it will be necessary to specify a UFD on the disk volune 
you are currently using, that is, vsdnere your home directory is. For 
exanple, when developing a new disk volume with UFD names identical to 
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those on another disk, it is necessary to carefully specify which disk 

is to be used each time a pathname is given. The current disk is 

specified by — 

<*>BEECH>BRANCH5 



for exanple. Do not confuse "<*>", meaning current disk, 
V(hich means hone directory. 



with "*>", 
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SYSTEM ACCESS 

Introduction 

The remainder of this section is a brief overview of some of the 
fundamental features of the PRIMOS operating systsn. It assumes that 
you are a EASIC/VM programmer with previous experience on an 
interactive canputer system, although possibly not on a Prime computer. 
It also assumes that you have read the concepts and definitions in 
Appendix D, or that you are already familiar with roiMOS terms. The 
commands introduced here allow you to: 

• Gain admittance to the computer system (LOGIN) . 

• Change the working directory (ATTACH) . 

• Create new directories for work organization (CREATE). 

• Secure directories against intrusion (PASSWD) . 

• Remove directories which are no longer needed (DELETE) . 

• Examine the location of the working directory and its contents 
(LISTF) . 

• Look at the availability and current usage of system resources 
- space, users, etc. (A\AIL, STATUS, USERS). 

• Create files at the terminal (also see Appendix D, EDITOR). 

• Rename files (CNAME) . 

• Determine file size (SIZE). 

• Examine files (SLIST) . 

• Print files (SPOOL). 

• Remove unneeded files (DELETE) . 

• Allow controlled access to files (PROTEC) . 

• Complete a work session (LOGOUT) . 

ACCESSING THE SYSTEM 

In order to access or work in the system, the user must first follow a 
procedure known as 'login'. 'Logging in' identifies the user to the 
system and establishes the initial contact between system and user (via 
a terminal). Once logged in, the user has access to a working 
directory (work area) , to files and to other system resources. The 
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format of the LOGIN command is: 

LOGIN ufd-name [password] [-ON nodename] 



ufd-name Ihe name of your login directory. 

password mst be included if the directory has a 

password. 

-ON nod ename ijsed for remote login across PRIMENET 
network. 

Example ; 

LOGIN DOUROS NIX 

DOUROS (21) LOGGED IN AT 10 '33 112878 

The nunber in parentheses is the PR IMOS-as signed user nunber (also 
called 'job' nunber). The time is expressed in 24-hour format. The 
date is expressed as miriddyy (Maniih Day Year) . The word NIX, in this 
example, is the password on the login directory. 

When logging into the systan, typing errors, incorrect passwords, etc., 
may cause error messages to be displayed. Most are self-explanatory; 
for a detailed discussion, see the New User's Guide to EDITOR and 
RUNOFF. 



DIRECTORY OPERATIONS 

^^■^^irS the Wbrking D irectory 

After logging in, the user's working directory is set to the login UFD 
by FRIMOS. The user can move to another directory in the PRIMOS tree 
structure (i.e., attach) with the ATTACH command. Ihe format is: 

ATTACH new-directory 

new-director y is the pathname of the new working directory. 

Note 

If any of the directories in the pathname have 
passwords, the entire jathname must be enclosed in 
single quotes, as in: 

A 'BEECH SECRET>BFIANCH5' 

To set the MFD of a disk as the working directory, the format is 
slightly different: 
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ATTACH '<volune>MFD mfd- password' 

vol one is either the literal volune name or the logical disk nunber, 
^^ tn£d-password is the passwDrd of the MFD. A password is always 
required for a MFD. 



Recovering from Errors ]fhile Attaching ; If an error message is 
returned following an ATTACH command (for example, if a UFD is not 
found) , the user ronains attached to the previous working directory. 

Creating New Directories 

To organize tasks and work efficiently, it is often advantageous to 
create new sub-UFDs. These sub-UFDs can be created within UFDs or 
other sub-UFI^ with the CREATE command. They can contain files and/or 
other sub-directories. The format is: 

CREATE pathname 

The pathname specifies the directory in which the sub-UFD is being 
created, as viell as the name of the new directory. 

Example : 

CREATE <1 >TOPS >M IDDLE >BOTTOM 

The sub-UFD BOTTOM is created in the UFD MIDDLE, which in turn is found 
in the MFD TOPS. 

TVo files or sub-UFDs of the same name are not permitted in a 
directory. If this is inadvertently attonpted, FRIMOS will return the 
message: ALREADY EXISTS. 

Assigning Directory Passwords 

Directories may be secured against unauthorized users by assigning 
passwords with the PASSWD command. There are two levels of passwords: 
owner and non-owner. If you give the ovvner password in an ATTACH 
comnand, you have owner status; if you give the non-owner password in 
an ATTACH command, you have non-owner status. Files can be given 
different access rights for owners and non-owners with the PROTEC 
command (see Controlling File Access) . 

The PASSED command replaces any existing password (s) on the working 
directory with one or two new passwords, or assigns passwords to this 
directory if there are none. The format is: 

PASSWD owner-password [non-owner-password] 

The ower-password is specified first; the non-ovsner-password , if 
given, follows. If a non-owner password is not specified, the default 
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is null; then, any password (except the owner pesswDrd) or none allows 
access to this directory as a non-owner. 



Exam pi e : 



OK, A DOUROS NIX 
OK, PASSWD US "THEM 



The old password NIX is replaced by the owner password US, and the 
non-o\rtner passward THEM. 



te 1 e ting Di rectories 

Wien directories are no longer needed they may be removed from the 
system to provide more room for other uses. The DELETE canmand can 
also delete empty subdirectories from a given directory. The format 

is: 

DELETE pathname 

Sub~UFDB that are not empty, i.e., that still contain files or 
subdirectories, cannot be deleted with this coimand. All entries in 
the directory must be deleted f;-rst. If an attempt is mac^e to delete 
directories containing files, PfllMOS prints the message: 

DIRECTORY NOT EMPTY 



BiKaminirg Co ntents of a Dir ecto ry 

After logging in or attaching to a directory, the user can examine the 
contents of this directory with the LISTF command vhich generates a 
list of the files and sub-directories in the current directory. The 
fonnat is: 

LISTF 

For example: the working directory is called LAURA; the following 
list will be generated vihen LISTF is entered at the terminal: 

OK, LISTF 

UFD=LAURA 6 OWNER 

$QUERY BOILER EX LETTER QUERY OLISTF BASICPROGS 

OUTLINE SOUFLINE MQL $MQL $LETTER MQL. LETTER FTN10 

EXAMPLES FUriL.10 $FUTIL. 10 

OK, 

The number following the UFD-name is the logical device nunber, in this 
case, 6. The words OWNER or NONCMN follow this nunber, indicating the 
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status in this directory. (See Securing Directories) 



If there are no files contained in a directory, .NULL. is printed 
instead of a list of files. 



SYSTEM INFORMATION 

Table 2-2 summarizes useful information you may need about the systan 
and how to obtain it. 
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Table 2-2 
Useful Eiystem Information 



Item 

Number of users 

User login UFD 

User number 
User line number 

User physical device 
Open file units 

Disks in operation 

Assigned peripiieral 
devices 

User priorities 

Other user numbers 

Your phantom 
user number 

Network information 

Login nodename 
Records available 

System time and date 

Computer time used 
since login 



Used to 

Indicate system 
resource usage and 
expected performance. 

Identify user v^o 
spooled text file 
(printed on banner) . 



Change tenninal 
characteristics. 



Avoid conflict when 
using files. 



Tell if spool printer 
is working; if devices 
are available. 



Log out your phantoms. 



Tell if network is 
available. 



Tell if there is enough 
room for file building, 
sorting, etc. 

Perform time logging 
in audit files. 

Measure program 
execution time. 



PRIMPS conmanj^s 

STATUS USERS (user list) 
LEERS (number of users) 



STATUS, STATUS UNITS 

STATUS 
STATUS 

STATUS 

STATIB, STATUS UNITS 

STATUS, STATUS DISKS 
STATLB LBE1=?S 

STATUS USEI« 
STATUS USEIRS 
STATUS USEfS 

STATUS, STATLK NET 

STATUS, STATUS UNITS 
AVML 

EATE 
TIME 



r«v. 
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Spool queue contents Tell if job has been 

printed. 

CX queue contents Tell if job has been 

completed. 



SPOOL -LIST 



CX ^'LL 



Note 



Any information given by any STATUS command is also given by 
the STATUS ALL command. 
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FILE OPERATIONS 



Cc-ea t i ng and Mod i f y i n g F i 1 es 

Text files may be created and modified using the text editor (ED) . 
Files may be transferred from other systems using maqnetic tape (MAGNET 
conmand) , or i;»per tape (RASIMP command) . See Reference Guide, PR:LMOS 
Commands for more details on these commands. 

Changing File Names 

It is often convenient or necessary to change the name of a file or a 
directory. This is done with the CNAME command. The format is: 

CNAME old-name new-name 

:2fJ3"35.®, is the pathname of the file to be renamed, and new-name is the 
new filename. ' 

Example: 

CN TOOLS >FORTRAN>rEST OLOTEST 

The file named TEST in the sub-lFD FORTRAN in the UFD TOOLS is changed 
to OLDfrEST. Since no disk was specified all MFDs (starting with 
locjical disk 0) are searched for the UFD TOOLS. 

■'^- 'i®^"'}^?^ already exists, PRIMOS will display the message: 

ALREADY EXISTS 

An incorrect old-name prompts the message: 

NOT FOUND 
ER! 



Determining File Size 

The size (in decimal records) of a file is obtainecl with the SIZE 
command. This coitmand returns the number of records in the file 
ijpecified by the given pathname. The number of records in a file is 
defined as the total number of data words divided by 448. However, a 
,iero-word length file always contains one record. TVie format is: 

'3 IZ E pathname 

Exa mple : 

OK, SIZE GLOSSARY 

itEV. ;! _ is^ 
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GO 



OK, 



14 RBCCRDS IN FILE 



Examining File Contents 

Contents of a program or any text file can be examined at the terminal 
with the SLIST coitmand. The format is: 

SLIST pathname 

The file specified by the given pathname is displayed at the terminal. 



Obtaining Copies of Files 

Printed copies of files from a line printer are obtained with the SPOOL 
command. It has several options, some of v^ich will not apply to all 
systems, as systems may be configured differently. The format is: 



SPOOL pathname 

PRIMOS makes a copy of pathname in the Spool Queue List 
printer, and displays the message: 

YOUR SPOOL FILE IS roTxxx (length) 



for the line 



XXX is a 3-digit number wliich identifies the file in the Spool Queue 
List. The reason for a list, rather than just having each file spooled 
out as the request comes, is that some requests are very long - 
hundreds of pages. PRIMOS spools out the shorter files as soon as 
possible, rather than make the user wait vrfiile the long files are 
printed. The length (SHORT or LONG) v*iich follows the SPOOL message is 
tlie category to vvhich the file has been assigned. It is possible to 
check the status of a SPOOL request by giving the command: 

SPDOL HLIST 



Example ; 

OK, SPDOL $S2. 3057 

GO 

YOUR SPOOL FILE IS PRT006 (LONG) REV 15.2** 

OK, SPOOL -LI ST 
GO 

USER FILE EftTE/TIME OPFS SIZE WKIAE 



FORM DEFER 
W.WIBA 



SOPHIE PRT005 10/25 14:26 S 
TEKI^IAN PRr006 10/25 15:45 L 



5 $UNFUNDED 
22 $S2.3057 
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OK, 

To cancel a spool request, the command format is: 

SPOOL -CANCEL PRTx>:x 

XXX is the number of your Spool File. 

For example: 

OK, SPOOL -CANCEL PRT013 

GO 

PRT013 CANCELLED. 

OK, 

Deferring Print i ng ; The -DEFER option tells the Spooler not to begin 
printing the indicated file until the system time matches the time 
specified with DEFER. This also permits you to enter SPOOL requests at 
your convenience, rather than waiting for the appropriate hour. 

Spexrify the DEFER option by: 

SPOOL filename -DEFER 'time' 

The value for ' time' can be expressed either in 24-hour format (00:00 = 
Midnight) or in 12-hour format followed by AM or FM (12:00 AM = 
Midnight). The format for ' time ' is 'HH:NN', where HH is hours, ":" 
is any character, and MM is minutes. If you specify -DEFER but omit 
time you will get the prompt: 

ENTER DEFERRED PRINT TIME: 

If ' time' is not in the correct format, you will get the above prompt 
again, plus this informational message: 

CORRECT FORMAT IS HH:MM AM/PM. 

Printin g o n Spe cial Forms: Line printers traditionally use one of two 
types of paper — "wide" listing paper, on which most program listings 
appear, and 8-l/2xll-inch v^iite paper, \N*iich is standard for memos and 
documentation. Computer rooms often stock a variety of special paper 
foHTis for special purposes, such as 5-copy sets, prej-printed forms 
(checks, orders, invoices) , or odd sizes or colors of pai)er. 

Request a specific form by: 

SPDOL filename -FORM form-name 

form^name is any six-character (or less) combination of letters. A 
list of available form namejs should be obtained from the system 
Administrator. 
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Deleting Files 

When files or programs are no longer needed they may be removed from 
the system to provide more room for other uses. 'The DELETE command 
deletes files from the working directory. The format is: 

DELETE pathname 



Controlling File Access 

Assigning passwords to directories allows users working in a directory 
to be classified as owners or non-owners, depending upon Oiich password 
they use with the ATTACH command. Controlled access can be established 
for any file using the PROTEC command. This contnand sets the 
protection keys for users with owner and non-owner status in the 
directory (see Assigning Directory Passwords above). The format is: 

PROTEC pathname [owner- rights] [non-owner-rights] 

pathname The name of the file to be protected. 

own er- rights A key specifying owner's access rights to file 

(original value=7). 

non-owne r-r igh ts A key specifying the non-owner's access rights 

(or ig inal val ue=0 ) . 

The values and meanings of the access keys are: 



key 


Rights 





No access of any kind allowed 


1 


Read only 


2 


Write only 


3 


Read and Write 


4 


Delete and truncate 


5 


Delete, truncate and read 


5 


Delete, truncate and write 


7 


All access 




Note 



Example : 



The default protection keys associated 
with any newly created file or UFD are: 
7 0: the owner is given ALL rights and 
the non-owner is given none. 



PROTEC <OLD>MYUFD>SECRET 7 1 
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In this example, protection rights are set on the file SECRET in the 
UFD MYUFD so that all rights are given the owner and only read rights 
are given the non-owner. 



CCMPLEriNG A WCRK SESSION 

When finished with a session at the terminal, give the LOGOUT command. 
The format is: 

rXODUT 

PRIMOS acknowledges the command with the following message: 

UFD-name (user-number) LOGGED OUT AT (time) (date) 
TME USED = terminal.- time CPU-time I/O-time 



user-number The one assigned at LOGIN. 

termina l-time Tne amount of elapsed clock time between LOGIN and 
LOGOUT in hours and minutes. 

^^ttyiie Central Processing Unit time consumed in minutes and 

seconds. 

T/ O-t i m e The amount of input/output time used in minutes and 

seconds. 

It: is good practice to log out after every session. Tt-iis closes all 
files and releases the PRIMOS process to another user. However, if you 
forget to log out, there is no s-.erious harm done. The system will 
automatically log out an unused terminal after a time delay. This 
delay is set by the System Administrator (the default is 1000 minutes 
but most System Administrators will lower this value) . 



REV. 2 - 22 



PER 3058 USING BASIC/VM 

SBCTICN 3 
USING BASIC/VM 



INTRODUCTION 

This section is an overview of all the basic concepts and commands you 
need to work with BASICAM. The first part discusses elementary tasks 
and the ccmmands needed to do them; the second part expands on some of 
the features introduced in the first part. 



ENTERING THE BASICV SUBSYSTEM 

From PRIMOS command level, it is possible to access any of the 
subsystems available under PRIMOS. To enter the BASICV subsystem, type 
BASICV. The system then responds with the following message and 
prompt : 

OK, BASICV 
BASICV REV 16.0 
NEW CR OLD: 



The 'NEW or OLD: ' prompt asks you to specify whether a new file is to 
be created or if an OLD, or previously created file is to be called 
from the current working directory to your working area in BASIC/VM. 
Type either OLD or NEW followed by the name of the file you wish to 
access or create. Remember that all command-line input must be in 
upper case only. 

Calling an OLD File 

The directory from vdnich you gave the 'BASICV command is your current 
working directory. It is referred to as 'the foreground' in BASIC/VM. 
A file that is currently open (and being edited, created or run) in 
this working directory is called the foreground file. Only one file 
can be in the foreground at any time. 

When you type OLD followed by a filename (or pathname) in response to 
the first prompt, BASICV locates the file and makes it the foreground 
file. For example, if you want to call a file natied JUNK to the 
foreground, type: 

X3LD JUNK 
> 
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The system responds with the right angle bracket, indicating that you 
are now at BASICV command level. This angle bracket is the compiler's 
prompt character. If a file or pathname is not specifie<a after OLD, 
the system prompts for it: 

NEW OR OLD: 01^ 
OLD FILE NAME: JUNK 
> 

If the file is in your current directory, a filename is sufficient; 
otherwise, a pathname (see Appendix D for definition) must be 
specified. The latter part of this section outlines how to access 
files in directories other than the current one. 

Entering A New File 

To enter a new program at the terminal , type NEW followed by a name for 
the file you wish to create. If a filename is not specified, BASICV 
will ask for one. 

Example : 

NEW CR OLD: m^ 
NEW FILENAME: TEST 
> 

This new file becomes the foreground file. It remains in the 
foreground until an OLD file is called in or you decide to create 
another new file. 

USING BASICV COMMANDS 

Now that the preliminaries are out of the way, you can create a new 
program or work with an existing one. Programming in BASIC/VM involves 
several routine operations which every user needs to be familiar with. 
The following is a list of these operations and the BA£iIC/VM conmands 
that can be used to accomplish them: 

• Displaying contents of current working directory (CATALOG) 

• Displaying contents of foreground file (LIST) 

• Displaying contents of non- foreground file (TYPE) 

• Saving a NEW or modified file (FILE) 

• Running a foreground program (RUN) 
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• Checking for syntax errors (COMPILE) 

• Translating source program into executable machine language 
(CCMPILE) 

• Executing a compiled source program (EXECUTE) 

• Editing a file (simple techniques, e.g., deleting lines) 

• Combining two or more programs (LOAD) 

• Renaming a foreground file (RENAME) 

• Removing files from a directory (PURGE) 

• Exiting the BASICV subsystem (QUIT) 

Examining Directory Contents; CATALOG 

The BASICAM CATALOG command returns a list of all the files in the 
current working directory. It has several options which provide 
additional information about the files. The format of the command is: 

CATALOG [options] 

Where options are one or more of the following: 

a\TE Date and time the file was last modified. 

PROTECTION Owner or non-owner protection attributes 
~ (see RRIMOS, Section 2). 

SIZE Number of records in each file. 

TYPE Describes file type (DAM, SAM, 

~ SEGSAM, SEGDAM, UFD; see Appendix D) . 

ALL Gives all of the above option information. 

If no options are specified, only the filenames are displayed. Cation 
abbreviations are underlined. 
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Example: 














XIATALOG A 




















PASSWORD 








Size 


Type 


Owner 


Nonowner 


Time 


Date 


FRiisrrx 


1 


sm 


0:FWD 


N:NIL 


10:48:24 


9/20,778 


TAB 


1 


SAM 


0:RWD 


N:lSfIL 


10:54:12 


9/20/78 


BASICreOGS 




UFD 


0:HVD 


N:NIL 


14:50:16 


9/05,^8 


MAT 


1 


SAM 


0:RWD 


N:NIL 


11:32:44 


9/20^'78 


OUTLINE 


3 


SM 


0;RVD 


N:NIL 


16:54:35 


8/25/78 


$DUTLINE 


3 


sm 


0:RWD 


N:NIL 


14: 20: 36 


8/37/78 


AGES 


1 


sm 


0:RWD 


N:NIL 


11:41:00 


9/12/78 


MATOEX 


3 


DAM 


0:FWD 


N:NIL 


11:36:12 


9/20/78 


AOCUM 


1 


SAM 


0:HVD 


N:NIL 


12:17:40 


9/06/78 


SECRET 


1 


SAM 


0:FWD 


N:R 


9:41:52 


9/^2/78 


OTHER 


1 


SAM 


0:RD 


N:NIL 


9:40:40 


9/22/78 


CQviPILEX 


3 


DAM 


0:PWD 


N:NIL 


10:15:40 


9/37/78 


PERSOmL 


1 


sm 


DiFWD 


N:NIL 


11:17:56 


9/12/78 


Displayinq Contents of 


ForegroLnd File 









The LIST and LISTNH commands display all or part of the foreground file 
at the terminal. LIST displays a program header including the program 
name, date and time; LISTNH omits the header. Ihe format is: 



LIST 
LISTNH 



[line-number-1, . . .line-number-n] 



If the line number options are specified, only the indicated line 
numbers are displayed. If omitted, the entire program is displayed. 

Displayinq Non-Foreground Fil es 

Non- foreground files can be listed at the terminal with the TYPE 
cortmand. Ibis is useful for comparing programs. A TYPEd file does not 
beccsne the foreground file; its contents are merely displayed on the 
user terminal. To modify or run the file (if it is a program) , use the 
OLD command to bring it to the foreground. The format of the TYPE 
command is: 

TYPE pathname 
^^■"^ pathname is the pathname or filename of a non-foreground file. 

The following example illustrates a situation \i\ere the file called XYZ 
IS in the foreground and a list of the file AGES is needed. 
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Example: 

(XYZ is in the foreground) 
>TYPE AGES 



10 REM AGES 

20 DATA 1952, 1956, 1957 

30 READ Y1,Y2,Y3 

35 INRIT 'ENTER THE CURRENT YEAR': Y 

40 A1=¥-Y1 

50 A2=Y-Y2 

60 A3=^-Y3 

65 PRINT Al, A2, A3 

70 END 

>LI§I (XYZ is still in foreground) 

XYZ TUE, SEP 12 1978 11:30:30 

(etc.) 

Saving a New or Madified File 

A new file is entered into the system by typing the statements at the 
terminal in proper BASIC/VM form. Section 4 explains all statement 
syntax rules. All statements are preceded by line nunbers to 
distinguish them frcxn commands, like LIST and RUN, which are not 
preceded by line numbers. Use the error correction characters {" and 
?) , discussed in Section 2, to correct typing mistakes. When the 
entire program is entered, FILE it to ensure that a copy of it is saved 
for future use. If a new program is not FILEd, it will vanish when you 
leave the BASICV subsyston, or it will be overwritten v\*ien another file 
is called to the foreground. The FILE command writes a copy of the 
foreground file to disk under the name you specified in the NEW or OLD 
sequence. If you want to change the name of the file, simply specify a 
new name after the FILE command. Ihe format is: 

FILE [filename] 

Once a NEW program has been filed, it beccmes an OLD program. However, 
the file remains in the foreground until another replaces it. 
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Compiling the Source Code 

In order for a program to be run or executed, the source code must be 
translated, or CCMPILEd, into executable machine language. During the 
COMPILE process, the compiler parses the code for errors and produces a 
binary version of the source file that can be EXECUTed or RUN. This 
binary file is kept in user memory until the EXECUTE command is issued; 
it may optionally be named and saved to disk for future use by 
specifying a filename with COMPILE. The format of the COMPILE command 
is: 

COMPILE [filename] 

If a filename is specified, the binary version of the foreground source 
file will be stored on disk with the indicated name. 

Checkir^ for Syntax Errors 

The COMPILE process also checks for syntax errors in a NEW or OLD 
foreground file. Syntax errors include misspelling of statements or 
referencing an undefined variable. During this process the compiler 
parses each line in the file and weeds out the errors. These errors 
are collectively referred to as 'compile-time' errors, as distinguished 
from 'run-time' errors which are displayed when a program is actually 
executed or run. Ihe COMPILE process does not run the program; it 
translates the source code to binary form, looks for faulty lines, 
displays them, and indicates v*iat is wrong with each one. 

Most error messages are self-explanatory. For a complete list of error 
messages, see AH>ENDIX D. Errors uncovered by the COMPILE process can 
usually be corrected with simple edit procedures, discussed later in 
this section. 

Executing a Program 

After a program has been CCMPILEd, or translated into binary form, it 
can be executed with the EXECUTE conmand. EXECUTE accepts a pathname 
option; therefore, it can run either a foreground or non-foreground 
file. The format is: 

EXECUTE [pathname] 

If a pathname is specified, EXECUTE will do one of two things: if the 
pathname is that of an executable binary, the program will be executed 
immediately; if the pathname is that of a non-compiled £»urce program, 
the compiler first translates the code into executable form, then 
executes it. 
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When the EXECUTE cortmand is given without the pathname option, the 
currently compiled code in user manory is executed. If no such 
executable code exists, the foreground file is compiled, then executed. 
Remember, an executable binary version (machine language) of any source 
program must exist before the program can be executed. 

Run- time Errors 

The EXECOTE process also performs the additional function of displaying 
errors that occur during run-time. Run-time errors include faults in 
program logic or control, such as a READ after a WRITE to a sequential 
file. Usually, run-time errors impair program execution and can often 
prevent a program from running at all. Each run-time error is 
displayed at the terminal as it occurs, e.g., as the canpiler attempts 
to execute a faulty statement. 

Should a program not run to completion, it should be examined for logic 
errors and corrected as necessary. The BASIC/VM drugging cortmands, 
discussed in Section 7, are often helpful in detecting and rectifying 
such program control errors. 

RUNning a Program 

Foreground source programs can also be executed with the RUN command. 
RUN combines both COMPILE and EXECUTE processes'. It has no pathnane 
option, and therefore can run only foreground programs. RUN translates 
source code to executable machine language and executes it ittmediately. 
No binary file can be stored via this process. 

Unlike EXECUTE, RUN displays both compile-time and run-time errors, 
whereas EXECUTE displays only run-time errors. RIW also has a 
no-header option, NH v*iich suppresses the program header (name, date, 
time, etc.) at run-time. Execution may be instructed to begin at a 
specified point in the program by specifying the appropriate line 
number. The format of the RUN command is: 

RUN[NH] [statement-number] 

Remember, only the foreground file can be run with this command. 



March 1979 



SECTICN 3 PDR3058 



Editing a File 



There are some simple editing techniques useful in correcting the 
errors pointed out by COMPILE, EXECUTE and RUN. They incluSe deleting 
lines, inserting new lines, and retyping lines. More advanced editing 
procedures are covered in Section 7. The procedures discussed here 
allow you to add, delete or replace statement lines without specific 
editing contnands. 

• To delete a specific statement line, type the line number 
followed by a carriage return (CR) . 



• 



• 



To insert a new statement line anywhere in the program, type the 
appropriate line number, followed by statement text. The new 
line is automatically placed in correct numerical isequence. 

To replace a statement line, type the line number followed by new 
statement text. The new statement will overwrite the original. 

After a file has been edited or modified, be sure to FILE it so that 
the changes will be made permanent. 

Process of a BASIC/VM Progr am 

The steps typically taken in the creation of a EASIC/VM program are 
outlined in Figure 3-1. Not all the options that can be chosen in 
program development are included in this flow chart. Only the most 
commonly exercised options are sl-own. 
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USING BASIC/VM 



ENTER OLD 

OR 

NEW COMMAND 




PURGE 



NO 




NO 




NO 



YES 



( PRIMOS 1 



BASICV 



SYSTEM PROMF 
OLD OR NEW: 





NO 




COMPILE AND 
EXECUTE 
OR RUN 




DEBUG 
(FIX ERRORS) 



NEW 



ENTER NEW 
FILENAME 



INPUT 
TEXT 



SAVE (FILE) 
PROGRAM 



YES 



EDITING 
PROCESS 



Figure 3-1. Process of a BASIC/VM Program 
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Sample Program 

The following program demonstrates the use of simple editing techniques 
to correct errors displayed when the program is COMPILEd and EXECUTEd. 



OK, BASICV 
GO 



(enter BASICV subsystem) 



BASICV REV16.2 

NEW OR OLD: NEW SAMPLE 

>10 DATA 12.1,34,78 

>20 READ X,Y,Z,A 

>30 PINT X,Y,Z 

>40 END 

XTOMPILE 

30 PINT X,Y,Z 

INVALID WCRD IN STATEMENT 
>30 PRINT X,Y,2 
X:OMPILE 
>EXECUrE 



END OF EATA AT LINE 20 



> 15 LATA 10,20,3 
X:OMPILE 



>EXECUTE 

12.1 

>FILE 



34 



>QUIT 



(create NEW file) 



OK, 



(check for syntax errors) 



(correct misspelling of 'PRINT') 
(no more syntax errors) 

(run-time error: not 
enough data. Program stops) 

(insert new line to add more data) 
(program now compiles and 
executes without errors) 

78 
(program is o.k.; FILE to save) 
(leave BASICV) 

(back to FRIMOS!) 



Combining IVo or More Programs 

The LOAD command may be used to combine two or more BASICV programs to 
form a single executable program. Usually, LG^D is employed when 
appending an external file to a foreground one. Line numbers which are 
common to both programs are overwritten in the foreground file by those 
line numbers in the external or LQADed program. Otherwise, line 
numbers are interwoven. 

If a binary version of a program (compiled source code) is LCADed, it 
is stored in user manor y but does not become part of the foreground 
file. If the EXECirrE command, with no pathname option, is issued 
susbsequent to this LO^D, the just-LQADed binary code will be executed. 
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The following examples illustrate two ways in which programs can be 
combined with LCAD. 

Example 1 : 

1. Source files: 



GAME 

10 PRINT 

20 REM A MATH GAME 

30 A=7 



CALC 
110 B=23 

120 PRINT A,B 



100 PRINT A* A 

X3LD GAi'lE 
>LQAD CALC 



Foreground file now contains: 
10 PRINT 



100 PRINT A*A 

110 B=23 

120 PRINT A,B 



200 END 



200 END 



! GAME is now in foreground 
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Exanple 2: 

2. Source files: 



PROG 

10 PRINT 'A' 

20 A=l 

30 B=2 

40 PRINT A*B 



PROGl 

10 PRINT 

15 REM mOGl 

20 A =3 

30 B=5 

35 C=ll 

45 PRINT A,B,C 

55 END 



X 3LD PRCG 
>LOMD PROGl 



1 FROG is now in foreground 



Foreground file now contains: 

10 PRINT 

15 REM FROG 1 

20 A=3 

30 8=5 

35 C=ll 

40 PRINT A*B 

45 PRINT A,B,C 

55 END 



Statements 10, 20 and 30 
from PROGl overwrite 
those in FROG. 



Renaming a Foreground F ile 

The name of a foreground file can be changed with the RENAME command. 
The format is: 

RENAME new-filename 

Only the new name of the file need be specified. Be aware that this 
command merely changes the name of the foreground file and does not 
change the name of the file on disk unless it is FILEd. When the 
renamed file is FILEd, two copies of the same file will exist: the 
original file and the renamed file. 



REV. 



- 12 



PDR3058 USING BASIC /VM 



Deleting a File from a Directory 

To remove a file from a directory, use the PURGE command. The format 
is: 

PURGE [pathname] 

If no pathname is specified; the foreground file is deleted, otherwise 
the file indicated by pathnaTie is removed. 

EXITING THE BASICV SUBSYSTEM 

There are two ways to exit the BASICV subsystan and return to roiMOS 
coitmand level. They are: 

1. QUIT 

2. CTOL-P, BREAK (see Section 2) 

As explained in Section 2, CTRL-P and BREAK have the same overall 
effects. Both leave files open and can cause files to be truncated or 
otherwise garbled. It is advisable to type QUIT, v«*iich closes all open 
files, protecting them from unwanted modification. The QUIT command 
can only be used at coninand level, i.e., in response to the '>' prompt. 

If one of the alternatives to QUIT is used, C ALL (short for CLC6E ALL) 
can be typed upon returning to PRIMOS command level. In most cases, 
this will ensure that all files are closed and that no damage will be 
done to any of them unintentionally. 

Sometimes temporary files are left in the directory by the BREAK or 
CTRL-P methods. These are indicated by the characters T$ followed by 
four digits, T$nnnn, vAiere nnnn ranges from 0000 to 9999. To check for 
these temporary files, type LISTF (at FRIMOS command level) . To delete 
them, simply type EELETE followed by the T$ filename representation. 
For purposes of file integrity, it is recommended that BREAK and CTRL-P 
not be employed unless unavoidable (as in a long listirg when the user 
is not at command level) . 
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AI»ITIOM\L FEATURES 



"Il'ie following information deals with other features of BASICAW v\^ich 
may be of use to some programmers. These features include: 



• Accessing files in directories other than the current vvorking 
directory. 

• Using the BASIC/VM ATTACH command to change the working 
directory. 

• Running BASICA'M programs from PRIMOS level. 

• Modes of operation (or interpretation) in BASICAM. 

ACCESSING FILES IN REMOTE DIRECTORIES 

Accessing files in BASIC/VM is similar to the process previously 
described in Section 2. Hov\ever, there are some important variations. 
The following examples illustrate file access procedures for all 
possible file location situations. User input is underlined. 

Accessing a File in the Current UFD 

To access a file called OLDFl in the current UFD the format is: 

NEW OR OLD: OLD OLDFl 

Accessing a fi le in a sub-UFD in current UFD 

To access a file called 0LDF2 in a sub-UFD called SUBS, located in the 
current directory, the format is: 

NEW CR OLD: OLD *>SUBSX)LDF2 

The right angle brackets (>) indicate that the file is contained within 
the sub-UFD. The asterisk (*) means 'current UFD' and must be included 
in the pathname. 

Accessing a File in a UFD on Another Disk 

The general format of this procedure is: 

OLD <volume> 
<ldisk> 

The parameter volume is the name of the disk on vdnich the file is 
found. 
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For example, to access a file called FILEOK listed in a UFD called 
PROJECTS on a disk called SOFTWR, the following pathname would be 
typed: 

OLD <SOFTWR>PROJECTS>FILEOK 

If the disk number was 3, the following format wDuld be used: 

OLD <3:*R0JECTS>FILE0K 

If passwords are required on either the UFD or file, they are inserted 
after the directory-name requiring the password. 

Example: 

OLD <3>PR0JECTS SECRET>FILEOK 

In this case, the UFD PROJECTS is protected by the password SECRET. 

ATTACHing to a Directory 

The ATTACH command, discussed in Section 2, is used in BASIC/VM as well 
as in PRIMOS. I-fowever, like all BASICV coimiands, ATTACH cannot be 
abbreviated. 

Attaching to a sub-UFD in the Current UFD 

To ATTACH to a sub-UFD in the current UFD, the asterisk symhxsl is used 
to indicate the current directory. For example, to attach to a sub-UFD 
called PLAffi in the current directory, the format is: 

ATTACH *>PLAYS 

Attaching to a sub-UFD in Another UFD 

When attaching to sub-UFD in a UFD other than the current directory, 
the UFD name, and password, if any, must be specified. 

Example: 

ATTACH NUMBERS>DECIMAL 

The UFD-name is NUMBERS and the sub-UFD-name is DECIMAL. 
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Attaching to a UFD or sub-UFD on Another Disk 

Attaching to a UFD or sub-UFD on another disk is the same as in FRIMC6. 
A volume name of the disk is given, or a logical disk number, (Idisk) 
is specified in the pathname. For example, to attach to a sub- UFD 
called PEONIES listecJ under a passworded UFD called FLOWERS on logical 
disk nunber 5, the format vi»uld be: 

ATTACH <5> FLOWERS PASSWD>PEONIES 
The password on FLOWERS is PASSWD and is required in the pathname. 

RUNNING PROGRAMS FROM PRIMOS 

A previously created and filed ;3ASIC/VM program can be run from PRIMOS 
command level using the BASICV conmand. The format is: 

OK, BASIC V pathname 

where pathname is either the source or binary form of a EASIC/VM 
program. The specified file is then run, leaving the user at PRIMOS 
comnand level. 

Example: 

The following is a BASICATl program, called 'T'. 

10 PRINT 'SAMPLE' 

20 FOR 1=1 TO 10 

30 J=a+I 

40 PRINT I, J 

50 NEXT I 

60 PRINT 'END OF LOOP' 

70 PRINT 'YOU ARE NOW AT HIIMOS COMMAND LEVEL' 

80 END 
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The program is now run from PRIMOS corrmand level: 



OK, BASICV T 




00 






SAMPLE 






1 




1 


2 




3 


3 




6 


4 




10 


5 




15 


6 




21 


7 




28 


8 




36 


9 




45 


10 




55 


END OF 


LOOP 




YOU ARE 


NOW AT 


PRIMOS COMMAND LEVEL 


OK, 







MODES CF OPERATION IN BASIC/VM 

Ihere are three ways in v*iich BASIC/VM can interpret terminal input: 

• as a conmand (Corrmand mode) 

• as an executable statement (Immediate mode) 

• as a line-numbered statement (Program-statanent mode) 



Any response issued in response to the BASICV prompt 
by the compiler as one of the above. 



>' is interpreted 



Command mode : If a command, e.g., RUN, is issued at this level, the 
compiler interprets it as a command and executes it immediately. 
Cortmands are directives to the system. More details appear in Section 

4. 

Program-statement mode ; Statements entered with preceding line numbers 
are immediately stored in user menory as part of a program and are not 
canpiled or executed until the compiler is instructed to do so. More 
details on program composition are found in Section 4. 

Immediate mode : If a statement is entered without a line number, the 
compiler checks to see if it is executable, then attempts to execute 
it. Any errors in statement syntax are displayed immediately. These 
statements are not stored in user memory and cannot be stored as part 
of a program. 
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Immediate mode is useful for debugging progranvs, displaying local 
variable contents and for performing quick calculations. Immediate 
mode is also referred to as 'deisk-calculator' mode. 

When performing calculations, values for defined variables are placed 
in temporary storage locations;; they remain intact until the variable 
is changed by some subsequent arithmetic operation. To clear all 
storage locations, and thereby reset all strings and numeric variables 
to null or zero values respectively, use the CLEAR command. 

The following is an example of an Iitmediate mode terminal session. 
User input is underlined for clarity. 



Example: 

>A=12 
:> B=25 

:> PRINT c 

37 

>DIM A (3) 

>A(1)=13 

:> A(2)=45 

> A(3)=56 

> PRINT A 

12 

:> MAT miNT A 
13 



> CLEAR 

> FRINT A 



: ^RINT B 



>PRINT C 



>MAT PRINT A 



45 



(l^erforming simple calculations) 

(define matrix) 

(assign values to matrix elanents) 

(variable A and matrix A have the same 
name but different values) 

56 

(clear all variable storage locations) 

(all variables are now zeroed) 



UNDEFINED MATRIX AT LINE (no matrix definition exists 

after CLEAR) 
>QUIT 
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ELEMENTS OP BASIC/VM 

LANGUAGE ELEMENTS 

BASIC/VM is composed of the following elements: 

• COMMANDS, v\*iich give directions to the system 

• STATEMENTS, which make up programs 

• EXPRESSIONS, v\*iich are combinations of operators and operands: 

• OPERANDS, vAiich are data elements including: 

constants 

variables 

functions 

arrays 

matrices 

• OPERATORS, of four types, vAiich manipulate operands: 

arithmetic 
logical 
relational 
string 

The above elements are defined briefly in this section. Additional 
information on each may be found in other sections of this manual as 
indicated. 

BASIC/VM uses the full ASCII character set including: 

1. Letters frc«n A-Z 

2. Digits from 0-9 

3. Special Characters (see list in ^pendix B) 

OPERANDS 

Within the context of a program, constants, functions, (or function 
references) , variables and arrays are referred to as operands because 
they are operated on or manipulated by operators. Operators, like 
addition (+) or subtraction (-) , tell a program what to do with the 
operands they connect. 
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Constants 



A constant can be either a number or a quoted literal string. Its 
value does not change during the execution of a program. 

Numeric Constants ; are positive or negative integers, decimal or 
exponential expressions. BASIC,A/M supports double-precision, floating- 
point numeric data, with a level of accuracy to 13 significant figures 
in the mantissa and 2 significant figures in the exponent. 

Examples: 

8.88 

-123 

2.5E-2 

Literal String Const ants: are a sequence of characters enclosed within 
single quotes or apostrophes ('). All spaces enclosed in the quotes 
are included in the string value. The maximun length of a string 
constant is 160 characters. See Section 12. 

Examples: 

•X,Y,Z' 

' ' (a null string) 

'BASIC IS FUN!' 

'VOITCH' 
Variables 

Variables are representations of data to v\*iich values are assigned. 
BASIC/VM supports both numeric and string scalar variables, and numeric 
and string subscripted variables, also known as arrays. Table 4-1 
gives examples of legal and illegal variables in BASIC/VM. 

Numeric Scalar Variables ; are single letters (A-Z) optionally followed 
by a single digit (0-9) . There are 286 possible ccxnbinations. Numeric 
scalar variables, also called simple numeric variables, are initialized 
by the BASICV subsyston to at the start of the program in v\diich they 
are defined. See Section 11. 



REV. 4 - 



PDR3058 ELEMENTS OF BASIC/VM 



Examples: 

A2 Initial Value: A2=0 

X4 Initial Value: X4=0 

String Scalar Variables : are single letters (A-Z) followed by a 
decimal digit and a dollar sign($) or by a dollar sign alone. String 
scalar variables, also called simple string variables, represent 
character strings of various lengths and are initialized to null at the 
beginning of the program in which they are defined. See Section 12. 

Examples: 

B$ 

A2$ 

Numeric Subscripted Variables (arrays) : are simple variables followed 
by one or two values enclosed in parentheses. An array name is a 
simple numeric variable, e.g., A. A single subscripted variable, e.g., 
A(l) , refers to an element in a one-dimensional array named by A. A 
variable with two subscripts, e.g., A(l,2) references an elanent in a 
tvvo dimensional array. Arrays and matrices are defined by the DIM 
statonent or a MAT statanent. See Section 9 for details. 

String Subscripted Variables (arrays) : are simple string variables 
followed by one or two values enclosed in parentheses. String arrays 
or matrices are named by simple string variables, and are dimensioned 
with a DIM or MAT statanent. String array elonents are represented by 
singly or doubly subscripted string variables. See Section 9 for 
details. 

Examples: 

A (4) one-dimensional numeric array elanent 

A$(3,4) two-dimensional string array elanent 
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Table 4-1. Legal and Illegal Variables 



Variable 










Type 


Legal 




Illegal 




numeric 


A2 


A 


ABl 


AR 


scalar 


X4 


Z 


XI 4 


BZ 


string 


B$ 




AB$ 


AB3$ 


scalar 


A2$ 




A21$ 




numeric 


A2(l) 


A(l,2) 


A12{1) 


A{1,2,1) 


subscripted 


A(l) 


A2(l,2) 


AB(1,2) 




string 


A$(l) 


A$(l,2) 


A12$(l,2) 




subscripted 


A2$(4) 


A21$(1,2) 


AB$(1) 




Functions 











BASIC/VM provides a variety of nuneric and string system functions 
e.g., TAN, COS, LEN, to operate on nuneric and string data. Users may 
also define their own numeric and string functions, known as 
user-defined functions. See Section 10 for details. 

Numeric Functions : are identified by a three or four letter name, 
followed by parenthetically enclosed nuneric items or parcameters. They 
specify an operation to be performed upon the nuneric itans to produce 
a single value. Table 10-2 lists all available numeric functions. 
User-defined nuneric functions are identified by the letters FN, 
followed by a simple numeric variable, (e.g., ET;JA, FNA8) .. 

String Functions : are identified by a three to five letter nane, 
followed by parenthetically enclosed string or numeric parameters. 
String functions are used to return information about strings and 
portions of strings, or to convert a numeric item to its corresponding 
string representation, and vice-versa. All string system functions are 
listed" in Table 10-2. User-defined string functions are named by the 
letter FN followed by a simple string variable, e.g., FNQ$. 
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OPERATORS 

Within a program, the previously defined operands are combined with 
operators to form expressions. Operators specify v«*iat is to be done 
with the operands in these expressions, i.e., how they are to be 
evaluated. There are four types of operators: arithmetic, relational, 
logical and string. C{>erands, then, can be manipulated arithmetically, 
logically, relationally, or by string operators. 

Arithmetic Operators 

Arithmetic operators are of two types, unary or binary. Unary 
operators require only one operand, e.g., +7. They indicate the sign 
of the number. Binary operators require at least two operands, e.g., 
Al+7. The following table lists the arithmetic operators for BASIC/VM. 

Arithmetic Operators 



ERATOR 


DEFINITION 


EXAMPLE 


+ 


addition (unary positive) 


A+B, +A 


- 


subtraction (unary negative) 


h-B, -A 


* 


multiply 


A*B 


/ 


divide 


A/B 


or ** 


exponentiation 


A''B,A**B 


MOD 


remainder from division modulus 


A MOD B 


MIN 


select lesser value 


A MIN B 


MAX 


select greater value 


A MAX B 



Relational Operators 

Relational operators are used with conditional statements and statement 
modifiers. (See Section 6 for details.) There are six relational 
operators, as listed in the following table: 
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OPERATORS 
< 
> 







" \ 






-< \ 






"' 1 






=> 1 






<> \ 






X 1 


Str- 


ing 


Operators 



Rel a tional Operators 

MEANING 
less than 
greater than 
equal 

less than or equal 

greater than or equal 
not equal 



EXAMPLE 
A<B 
A>B 
A$=B$ 

A$<=C$ 

A=>C 
AOD 



String operators include the above relational operators plus a 
concatenation operator (+) for combining twa strings. String operands 
can only be used with string operators. 

Logical Operators 

Logical operators are connectives for relational expressions, allowing 
the testing of many relations at once. 



Logical Operators 

OPERATOR MEANING EXAMPLE 

AND true if both A and B are true A AND B 

OR true if either A, B or both are true A OR B 

NOT true if A is false NOT A 
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EXPRESSIONS 

Definition 

Expressions are ordered combinations of operands and operators or other 
expressions which are evaluated within a program to produce a single 
result. Expressions can be arithmetic, e.g., A + B, relational, e.g., 
A>=B, or logical, e.g., A AND B. 

Evaluation 

Expressions are evaluated in order of operational priority. The 
priority list from highest to lowest for BASIC/VM is listed below. 
Within each level the evaluation order is from left to right. 

( ) Parenthetical Expressions 

System and User-defined Functions 

" (or **) Exponentiation 

NOT, Unary (+ -) 

*, /, MOD 

+ , - 

MIN, MAX 

Relationals {=, >, <, =>, <=, <>) 

AND 
OR 

CCM1ANDS AND STATEMENTS 
Commands 

BASIC/VM system commands are directives to the BASICV subsystem to 
perform some iimiediate function. They are distinguished fran 
statements in that they are not preceded by a line number. A list of 
all BASICAM commands and statements appears at the end of this 
section. Some commands have optional parameters or argunents to 
further define the operation which they perform. A ccxnplete list of 
BASIC/VM command formats and definitions can be found in Section 14. 
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Statements 



Statements are part of a program, and as such, are preceded by a line 
number. When they appear without line numbers they are executed 
immediately. 

Example : 

PRINT 12*154 
1848 

This 'desk calculator' utilization is called Immediate Mode. 

Statgnent Syntax 

Statements must adhere to the following rules: 

1. Each statement must be entered in upper case letters. 

2. Each statanent must be contained on one line. 

3. Statements must not exceed 160 ASCII characters in length. 

4. Portions of the statonent (i.e., string literals) vAiich the 
user wishes processed verbatim must be enclosed in single 
quotes. 

5. Statements cannot be abbreviated. 

Statanents should be separated from their identifying line nunbers with 
a blank space to avoid misinterpretations. 

Statement Nunbers 

Statement numbers are one to five digit integers ranging from 1 to 
99999. Successive statements are generally numbered in ascending 
order. It is recommended that sjtatements be numbered in increnents of 
ten, e.g., 10, 20, 30... A statement may be added between lines 10 and 
20, for example, without changing the other statements. Given the 
following program: 

10 PRINT 'NAME' 

20 PRINT 'ADDRESS' 

30 PRINT 'CITY' 

> RUNNH 

NAME 

ADDRESS 

CITY 
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To insert a line between lines 10 and 20 and another between 20 and 30, 
add PRINT statements as indicated: 

> 15 PRINT 
> 25 miNT 
> RUNNH 
NAME 

ADDRESS 

CITY 



Comments 

Programs may contain comments or ronarks which serve as explanatory 
notes for the benefit of the reader. They are preceeded by the letters 
REM or by the exclamation mark, (!) . Comments may appear by themselves 
on separate lines or may be appended to a line with the exclamation 
mark. Comments may contain lower-case characters. 

Example: 

10 REM THIS IS A REMARK 

20 ! THIS IS A REMARK ALSO 

30 X=l ! set X equal to one 

LIST OF COMMANDS AND STATEMENTS 

The following table lists all available BASIC/VM system commands and 
language statenents with a brief description of their functionality. 
Also included are references to other sections in this guide v*iere more 
information on each conmand and statanent may be found. 
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Table 4-2 
List of Conmands and Statements 



Command 
ALTER 

ATTACH 

BREAK fai 1 
JOFF) 

CATALOG 

CLEAR 



CQVIINP 

COMPILE 

CONTINUE 

DELETE 
EXECUTE 

EXTRACT 
FILE 

LB PS 



Description Section 

Allows editing of a single line in a program 7,14 

using subconnmands , listed in Table 14-1. 

Attaches to a directory in BASICV subsystem 3,14 

sjaecified by pathname (similar to FRIMOS ATTACH 
but works in BASIC environment) . 

Sets and insets breakpoints at specified line 7,14 

numbers for debugging. Maximum of 10 
break points may be set. See LBPS. 

Lists all filenames under current UFD; options 3,14 

return other file-related information. 

Resets all previous numeric values to 0, or string 5,14 
values to null, deallocates previously defined 
arrays and closes all open files. 

Calls a spe<:ified conmand file to foreground; 6,14 

reads and executes commands until a COMINP TTY 
is reached. 

Translates a source file into executable binary 3,14 

form; displays syntax errors. 

Resumes program execution after a breakpoint 7,14 

or PAUSE. 

Deletes specified statement lines. 7,14 

Executes indicated program (binary or source); 3,14 

displays rui-time errors. 

Deletes all except specified lines. 7,14 

Saves all input and modifications to current 3,14 

(foreground; a specified program file; 
writes file to disk. 

Lists currently set breakpoints. 7,14 
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LIST[NH] 

LOAD 
NEW 

OLD 

PURGE 

QUIT 

RENAME 
RESEQUENCE 
RUN [NH] 



TRACE I ON 

)OFF| 

TYPE 



fON I 
I OFF J 



Displays the contents of current file at 3,14 

terminal. NH option suppresses header or program 
title. 

Merges or adds an external program to current 3,14 

(foreground) program. 

Indicates to compiler that a new file is to be 3,14 

created in foreground. New filename 
must be specified. 

Calls pre-existing file to current working area 3,14 

(foreground) . Makes it current file. 

Deletes specified file frati UFD; file 3,14,15 

must be closed. 

Returns control to PRIMOS from BASICV command 3,14 

level. 

Changes name of foreground file. 3,14 

Renumbers statement in current program. 7,14 

Initiates conpile and execute processes on 3,14 

current source program. 

Tests program logic; line numbers are displayed 7,14 

as correspondirg statonents are executed. 

Displays contents of specified non- foreground 3,14 

file at terminal. TYPE program does not replace 
program currently in the foreground. 



Statement 



Description 



Section 



ADD # 



CHAIN 



CHANGE 



Adds record to MIDAS file opened 
on specified file unit. 

Transfers program control to specified 
external program. 

Converts ASCII character string to one- 
dimensional numeric array or vice-versa. 



8,15 
6,15 



10,15 
APPB 
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CIjOSE # 

cmiNP 

DATA 

DEFINE FILE # 

DEF FN 



DIM 



DO...DOEND 



ELSE DO 



END 



ENTER [# ] 



FCR 



GOSUB 



GOTO 



IF 



Closes fil€i on specified unit(s) . 

Stops execution of current program: calls 
specified command file to foreground. 

Contains miner ic and string constants 
to be accessed by READ statement. 

Opens a file of specified type on indicated 
unit number with optional access 
restrictions (APPEND, READ, SCRATCH) . 

Without FNEND, defines one- line function 
with nuneric or string scalar variable 
arguments; with FTJEND, defines multi-line 
function. 

Defines dimensions of nuneric or string 
array or matrix. 

Defines a set of statements to be 
executed in association with 
IF-THEN statement pair. 

Optional alternative to DO-DOEND 
statanent set. 

Terminates program execution; no message 
is displayed. 

A timed input statonent: with # option, 
returns user-number assigned at LOGIN; 
also sets time-limit on input. 

Defines beginning and end of loop 
and loop index; used optionally with 
STEP, WHILE, UNTIL, NEXT. 

Transfers program control to internal 
subroutine: used with RETURN. 

Transfers program control 

to specif ie(3 line; can be used 

conditionally with IF or ON. 

Makes executable statements conditional; 
can be used with GOTO, THEN, ELSE DO, etc. 



8,15 
6,14,15 

5,15 

8,15 

10,15 

9,15 
6,15 

6,15 
6,15 
5,15 

6,15 

6,15 
6,15 

6,15 
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INPUT [LINE] 

LET 

MARGIN (OFF) 



MAT 




MATJINV) 
[TRNJ 

MAT INPUT 



MAT PRINT 



MAT READ 



MAT READ [*] # 



MAT WRITE # 



NEXT 

on(gosub] 

[GOTO j 



Requests data to be entered from 
terminal. LINE option accepts entire 
line, including ccarmas and colons, 
as one entry. 

Assignment statement: optional . 

Changes width of output lines. 

OFF option turns off margin checking. 



Sets initial value of matrix elements 
to zero, identity, null or one. 



Performs addition, subtraction or 
multiplication on two matrices. 

Calculates INVERSE or TRANSPOSE values 
of one matrix and assigns them 
to another. 

Reads data from a terminal and assigns 
values to elonents of specified 
matrix or matrices. 

Prints an entire matrix (or matrices) 
at terminal. 

Reads values fran data list(s): assigns 
them to elonents of matrix or matrices. 

Reads data from external file and assigns 
them to a specified matrix or matrices. 
Optional * forces all data in current 
record to be read before new one is read. 

Writes an entire matrix (or matrices) to 
a file on specified unit. 

Defines end of loop begun by a FOR statement. 

Transfers program control to a subroutine 
(GOSUB) or to one of a list of statement 
nunbers (GOTO) . 



5,15 

5,15 
5,15 

9,15 

9,15 
9,15 

9,15 

9,15 
9,15 
8,9,15 

8,9,15 

6,15 
6,15 
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ON END # GOTO 



ON ERROR [#] 
GOTO 



PAUSE 

POSITICN # 

PRINT 

PRINT USING 

READ 

READ [KEY] # 

READ LINE # 

READ [*] # 



REM 
REMOVE # 

REPLACE # 



Establishes a line number to which 6,15 

program control will transfer 
v*ien an END OF FILE occurs in disk 
file opened on specified unit. 

Defines statanent line to vrfiich program 8,8,15 

control will transfer when a 
run-time error occurs, in disk 
file, if # specified. 

Suspends program process at line vvtiere 7,15 

PAUSE occurs; to resume, type 
CONTINUE (ccmmand) . 

For DA disk files; positions internal record 8,15 

pointer to a specified record. 

Can be used with LIN, TAB, SPA options 5,14,15 

to print formatted data at terminal. 

Prints data output formatted according 5,15 

to format strings. See Table 15-2. 

Reads numeric or string values from a 8,15 

DATA statement in a program. 

Reads data associated with record key 8,15 

in MIDAS file opened on indicated unit. 

Reads from a disk file an entire line of 8,15 

text, including conmas, colons, as one 
data itan. 

Reads from current record in 8,15 

file open on specified unit; pointer then 

positions to next sequential record. 

* allows one record to be finished before 

a new one is read. (Holds pointer at current 

record after READ is complete.) 

Indicates a remark to the user only. 4,15 

Removes specific key fran MIDAS file; 8,15 

if primary key, removes associated data 

also. 

Deletes data files referenced by a 8, 15 

segment directory. Moves pointer from 
deleted file to another file; zeroes old 
pointer. 
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RESTORE 



[!] 



RETURN 
REWIND # 
WRITE # 
WRITE USING # 



Reuses list of data itatns beginning with 
first item in lowest numbered EftTA 
statement; # option reuses numeric itans; 
$ option reuses string items only. 

Returns control frcm subroutine to statement 
following GOSUB statement. 

Repositions record pointer to top of DA or 
MIDAS file open on specified unit. 

Writes data to current record of disk file 
opened on specified unit. 

Generates formatted output including 
tabs, spaces and column headings and writes 
output to ASCII disk file file opened on 
specified unit. 



5,15 

5,15 
8,15 
8,15 
8,15 
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EftTA INPOT/OUTPUT 



SECTION 5 
DATA INPUr/OlH'PLrr 



INTRODUCTION 

This section covers data exchange between programs and terminals, 
including various methods of formatting data output. The first part of 
this section deals with data input or the process of providing data to 
a program either fron within a program or from the terminal. The 
statQTients involved in data input are: 



• LET 

• DATA 

• READ 

• RESTORE 

• INPUT 

• INPUT LINE 

• ENTER [#] 



Assigns values to variables. 

Provides data values for associated READ 
statement . 

Reads values from DATA statement into a list 
of variables. 

Tells program to reuse data values from 
previous DATA statonent. 

Requests user input from terminal. 

Accepts entire line of terminal input as one 
datum. 

Timed input statanent; # option reads user 
login number into an indicated variable. 



The second part deals with data output, including the output of data 
from a program to a terminal or other output device. Data output 
involves the following statements: 

Prints data values verbatim or prints values 
associated with specified variable. 

Prints data with spacing conventions (tabs, 
blank lines, etc.) dictated by modifiers. 



Prints data according to format indicated by 
special format characters. 



• 


PRINT 




• 


PRINT 


tab) 

LIN I 
SPAJ 


• 


PRINT 


USING 



1 
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• MARGIN Alters data output line length by increasing 

or decreasing right margin from the default 
(80 characters positions) . 

Data exchange involving the transfer of information between a program 
and external data files is covered in Section 8, FILE HANDLING. 

UKTh INPUT STATEMENTS 

Assignment Statement 

The LET statement can be used to preface statsnents that assign values 
to variables and array elements; however, the use of LET is opt ional 
in BASIC/VM; it is not essential to the assignment process. The 
statonents 'LET A=6' and 'A^' are equivalent. 

Reading Data Lists 

The READ and DATA statements are used vhen all data values are known in 
advance and can be incltried directly in the program text. READ and 
DATA must always be used together. The READ statement lists numeric or 
string variables, separated by commas. The DATA statenent contains 
values v^ich correspond to the type (numeric or string) and number of 
variables listed by READ. If the items in a list exceed the length of 
one line, they may be continued in subsequent READ or DATA statements. 

Example: 

10 DATA 5,10,15,10 

20 DATA 2, 7.2 

30 READ Al, A2, A3,B,C,X 

40 mmr 'partial sum =' ,- ai+a2+a3 

45 PRINT 'PARTIAL SLM=';B-K:+X 

50 PRINT 'AVERAGE='; (AHA2+A34B-K:) A 

50 END 

>RUNNH 

PARTIAL SUM =30 

PARTIAL SUM=29.2 

AVERAGE =7 . 222222222222 

If there are more variables in the READ statanent than items in the 
DATA statement, an END OF EATA AT LINE nnnn message, where nnnn is a 
program line number, will appear at run-time. 
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Example: 

10 READ X,Y,Z,V,B 

20 DATA 12,67,89 

30 R=X+Y+Z4B 

40 PRINT R 

>RUNNH 

END OF EATA AT LINE 10 

If the DATA statanent contains more elements than there are variables 
in the READ statement, the extra values are ignored. 



Recycling Data Values 

The RESTCBE statement enables recycling of data values within a program 
without the need to re-enter them. The subsequent READ statement is 
directed to reuse the data beginning with the first value in the lowest 
numbered DATA statement. 
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Example: 



5 


READ X 


10 


PRINT 'LOOP = ':X:' TIMES' 


20 


PRINT 'FIRST VALUES OF Y ARE: ' 


25 


X=X-1 


30 


FOR A = 1 TO X 


40 


READ Y 


50 


PRINT Y 


60 


NEXT A 


70 


RESTORE 


80 


PRINT 'SECOND VALUES CF Y ARE: ' 


90 


FOR A = 1 TO X 


100 


READ Y 


110 


PRINT Y 


120 


NEXT A 


130 


DMA 5, 1, 3, 5, 7 


140 


END 



This program yields two different sets of values for Y, one for each 
time the variable is passed through the loop. When run, the program 
produces the following output: 

LOOP = 5 TIMES 

FIRST VALUES CF Y ARE: 

1 

3 

5 

7 

SECOND VALUES CF Y ARE: 

5 

1 

3 

5 

It is also possible to RESTORE only numeric or string values, using the 
alternate forms of the RESTORE statement. 

RESTORE # reuses all nuneric items, and 

RESTCXRE $ reuses all string itons, beginning with 
lowest-numbered EftTA statement. 
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Data Input From Tenninal 

The INPUT statement accepts data values from the user terminal. 
Multiple variables, both numeric and string, can be specified on the 
INPUT statement line. Values for each variable are then entered from 
the terminal at run-time. This feature allows data values to be varied 
each time the program is run, providing increased program flexibility. 
The default prompt is the exclamation point (!), which indicates that 
the program is awaiting tenninal input. 

Example : 

10 REM AVERAGE ANY 3 NUMBERS 

20 ERIWr 'GIVE ME 3 NUMBERS' 

30 INPUT A, B, C 

40 X = (A46-k:)/3 

50 PRINT 'THE AVERAGE IS:' :X 

60 END 

GIVE ME 3 NUMBERS 
! 10, 30, 50 
THE AVERAGE IS: 30 

The program asks for the input of any three numbers separated by 
commas. If the commas are omitted, the line is accepted as one entry 
and a second exclamation mark is printed indicating a second value is 
expected. If more items are entered than required, the extraneous ones 
are ignored. 

Since the default INPUT prompt (!) is not very informative, an 
alternate form of the statement allows the inclusion of a prompt 
string. Ihe format is: 



INPUT ['prompt-string',] var-1 [,...var-n] 



Example : 

10 INPUT 'INPUT YOUR FAVORITE COLOR", C$ 

20 PRINT C$: 'IS THE ICKIEST COLOR I EVER SAW!' 

Of course, some sort of prompt statement may be printed prior to the 
INPUT statement, as in the first example above. 

If commas must be included as part of your input, use the INPUT LINE 
statement v\hich accepts an entire line, including coitmas, as one entry. 
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10 PRINT 'WHAT IS YOUR NMAE AND AEDRESS ' 

20 INPUT LINE C$ 

30 PRINT 

40 PRINT C$: '-THANK YOU' 

50 END 

A £3ample output might be: 

WHAT IS YOUR NAME AND ADDRESS 

(user inputs info in response to ! prompt) 

I DOU PIAZZA, CLOUD NINE 

LDU PIAZZA, CLOUD NINE -THANK YOU 

Timed Terminal Input 

The ENTER statement serves the same purpose as INPUT but allows the 
user to specify a time limit on response requested from the terminal, 
as well as a variable to indicate the actual time used. The ENTER 
statement has no prompt , and therefore it is helpful to include a 
prompt of some sort prior to thie ENTER statement itself. The format of 
the ENTER statanent is: 

ENTER time-limit, time-limit-variable,| numeric-variable > 

[string-variable ) 

where the time-limit is expressed in seconds, time-limit-variable 
represents the actual time the user needed to respond, and the 
numer ic-var iable or string- variable is the variable for v*iich a value 
is expected from the terminal. 

In the following example, a value for Z is expected frcm the terminal 
and a limit of 5 seconds is placed on response time. T represents the 
time-limit-variable. 

Example: 

10 PRINT 'Enter a value for Z' 

20 ENTER 5,T,Z 

30 PRINT T 

40 H^INT Z 

>RUNNH 

Enter a value for Z 

22 

3 

22 

STOP AT LINE 40 
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The example stows that an input value of 22 was assigned to Z, and that 
the value was input in 3 seconds (T). If the time limit had been 
exceeded, the variable Z would have been set equal to zero and T wDuld 
have been reported as -5. 

Another form of EWTER, ENTER #, gets the user's login number (assigned 
at LDGIN time) and places it in a user-specified variable. The format 
is: 



, time-limit ,time-limit-var J num-var > 

[ str-var ) 



ENTER # user-num-var 

v^ere user-num-var is the nuneric variable which represents 

the user number. Other options are the same as for ENTER (above) . 

Example: 

> ENTER # U 
> PRINT U 
>2B 

The user's login number is 28 and is returned by printing the value of 
U. If a user-variable is not specified with ENTER #, an error will be 
displayed. 

Example: 

10 ENTER # T,5,H,P 

20 ERIWr 'YOUR USER NUNBER IS: ' :T 

30 PRINT 'P=':P 

40 PRINT 'YOUR RESPONSE TIME IN SECCNDS WAS:':H 

50 STOP 

> RUNNH 

112 

YOUR IBER NUMBER IS : 28 

P=12 

YOUR RESPONSE TIME IN SECCNDS WAS: 2 

STOP AT LINE 50 



DATA OLTTPUT STATEMENTS 

The results of data manipulations performed within a program are not 
displayed at the terminal unless some form of the PRINT statement is 
included in the program. The remainder of this section describes 
various methods of printing and formatting data using the PRINT 
statement and the formatting modifiers, LIN, SPA, TAB, and MARGIN. 
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Default PRINTing 

Without the use of formatting modifiers, the PRINT statement can 
acccmplish the following simple formatting tasks: 

1. Inserting blank lines in the output. 

2. Separating data into colunns (using commas). 

3. Spacing data items on a line (using colons or semicolons). 

4. Conditionally printing a line (with WHILE, UNTIL, etc.). 

The following program demonstrates the simple formatting of string and 
numeric values in two columns by using coitmas: 



10 PRINT 


'MATH CALCULATIONS ' 


20 PRINT 






30 PRINT 


•ADD', 'MULTIPLY' 


40 A=3 






50 B=7 






60 PRINT 






70 PRINT A-re, A*B 




80 END 






»UNNH 






MATH CALCULATIONS 




ADD 




MULTIPLY 


10 




21 " 



The PRINT statements on lines 20 and 60 each cause a single blank line 
in the output. Enclosing a string in single quotes in a PRINT 
statement causes the string to be printed verbatim. Separating more 
than one itan with conmas causes each item to be printed in a separate 
column. 

Column Separators ; The output from the PRINT statenent is normally 
divided into zones or columns of 21 characters each. The first zone 
starts in colunn 1, the second in colunn 22, etc. For the average 
printing page, the maximum nimber of zones is five. 

A coimia in a print list causes the terminal to advance to the first 
character position of the next available zone. If line overflow 
occurs, the current line is printed and a new line is started. If the 
last element of the print list is a comma, the partial line, if any, is 
printed and the cursor is positioned to the start of the next available 
zone. 
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Example: 

10 PRINT 'COL.l', 'COL. 22', 'COL. 43' 

20 PRINT 

30 A$ = 'NAME' 

40 B$ = 'ADDRESS ' 

50 C$ = 'PHONE NO.' 

60 PRINT A$, B$, C$ 

65 END 

When run, the following output results: 

COL. 1 COL. 22 COL. 43 

NAME ADDRESS PHCWE NO. 

Spacing Items ; Using a colon (:) in a PRINT statement causes output 
items to be separated by a single space. Using a semicolon (;) causes 
no characters to be placed between output items. The following example 
shows how a fiirase can be output in at least three different ways by 
using commas, semi-colons and colons in PRINT statements. 

Example: 

10 A$= 'COTTON' 

20 B$= 'CANDY' 

30 C$='IS' 

40 D$= 'STICKY' 

50 PRINT A$,B$,C$,D$ 

55 PRINT 

60 PRINT A$;B$;C$;D$ 

70 PRINT 

80 PRINT A$:B$:C$:D$ 

85 PRINT 

90 END 
> RUNNH 
COTTON CANDY IS STICKY 

COTTONCANDYISSTICKY 

COTTON CANDY IS STICKY 
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PRINTing Data With Modifiers 

In addition to the delimiters discussed above, the PRINT statement also 
takes three optional modifiers. They format output by forcing items to 
indicated tab positions, by inserting any nunber of spaces between 
items, and by inserting any number of blank lines between lines of 
output. 

TAB modifier ; A specific tab position may be indicated by the TAB 
mcxJifier followed by a parenthetical value representing the column 
number. 

Example: 

10 PRINT'COL.1';TAB(40); 'COL. 40' 

20 PRINT 

30 X=3'^ 

40 Y=X*50 

50 PRINT X;TAB(40);Y 

60 END 

>RUNNH 

COL.l COL. 40 

9 450 



SPA modifier ; A specific number of spaces may be forced between items 
in the output by the SPA modifier followed by a parenthetical value 
representing the number of blenk character positions. 

Example; 

10 PRINT SPA (5): 'COL. 5' 

20 PRINT 

30 X=5 

40 Y=X*5 

50 PRINT X;SPA(5);Y 

60 END 

>RUNNH 

COL. 5 

5 25 



LIN Modifier : A specific number of blank lines may be forced between 
items in one PRINT statsnent using the LIN modifier followed by a 
parenthetical value. This eliminates the need for consecutive PRINT 
statanents. 
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Example: 



10 PRINT 'COL.l' 

20 PRINT 

30 X=3'^ 

40 Y=X''2 

50 PRINT X;LIN(3);Y 

55 END 

>RUNNH 

COL.l 



81 



Note 

LIN (3) outputs three Carriage Return - Line Feed 
canbinations. LIN (-3) outputs three Line Feeds 
without Carriage Returns. LIN{0) outputs a 
carriage return without a Line Feed. 

Formatting With PRINT USING 

Additional formatting capabilities are provided by the PRINT USING 
statement in conjunction with a series of format characters. Both 
numeric and string data output can be formatted according to a field of 
special format characters, called a format string. This format string 
is included on the roiNT USING statement line prior to the list of 
items to be printed. The field may contain either numeric or string 
format characters, depending on the type of data to be formatted. 

There are seven special characters v^iich define numeric format: 

# . , '^ + - $ 

Table 15-2 in the reference section lists each character and several 
examples of its use. 

Ihe tt Sign: One or more pound signs (#) in a format string represent 
digit positions v\*iich will be occupied by the datum to be formatted. 
v\*iich is filled with the data provided in the statement. 
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Example: 

PRINT USING '##', 25 

Results in the output: 25 

Including too few pound signs for a non-decimal datum causes a row of 
asterisks to be printed. This indicates that the item to be formatted 
was too large for the specified field. For example: 

>miNr UBIN3 '####', 123456 
**** 

The period (.) : represents the position at vy*iich a decimal point should 
occur in the datum to be printed: 

PRINT USING '##.##', 20 

Results in the output: 20.00 

(Digit positions to the right of the decimal point will be filled with 
zeroes.) 

Note 

If too few digit places are specified in the format 
for a decimal number, the item will be rounded off 
as follows: 

40.325 = 40.32 
40.327 = 40.33 
40.323 = 40.32 

The cortma ( , ) ; represents a coitma in the corresponding position of the 
output unless all digits prior to the comma are zero. In that case, a 
space is printed in the corresponding coitma position. 

Examples: 

PRINT USING •#,###.##•, 2000 

Results in the output: 2,000.00 

PRINT USING •+#,###.##', 030.6 

Results in the output: + 30.6 
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The up arrow Q: is used in sets of four. Four up arrows indicate an 
exponent field vhich will be output as E+nn where nn is a two-digit 
number depending on how many places the decimal is moved in the format. 

Example: 

PRINT USING •#### ', 17.35 

Ftesults in the output: 173^H32 

Plus and minus signs (+ -): are used to indicate the value of a datum 
to be printed. A single plus sign placed in either the first or last 
character position of the format causes either a + or - sign to be 
printed in front of the item, depending on whether it is positive or 
negative. 

Examples: 

PRINT USING •+##.##', 25 

Results in the output: +25.00 

miNT USING •+##.##', -12.3 

ftesults in the output: -12.30 

how about 'PRINT USING '##.##-' -32 

Two or more plus signs placed in the first character positions of the 
format cause the aipropriate sign to be output immediately to the left 
of the most significant nonzero digit of the datun. The second through 
last plus signs may be used as digit positions similar to a # sign as 
required by the size of the item. 

Examples: 

PRINT USING •++##.##', 10.40 

Results in the output: +10.40 
PRINT USING '++++.##', 15.90 

Results in the output: +15. 90 

One or more minus signs have an effect similar to that described above. 
However, a positive datum will be preceded by a blank instead of a + 
sign. 
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Examples: 

PRINT USING '-##.##', 20.0 

Results in the output: 20.00 
PRINT USING •-#,###', -705 

Results in the output: - 705 

A dollar sign($); Oie or more dollar signs in a format string cause a 
dollar sign to be placed at the appropriate position in the printed 
itan. This position will depend on other format characters included in 
the format string. For example: 

> roiNr UBIN3 ■$###,###.##', 4600 
$ 4,600.00 

>P R INT USING '-$##.##', 40.325 
?'40.32 

>PRINT USING '$##.##', 40.325 
$40. 32 

> PR INT USING '-$$,###.##', -70 
- $070. 00 

> PRINT USING '+$$###.##', 70 
+ $070.00 

> PRINT USING '+$###.##', 7 
+$ 70.00 
> 



String Fields : There are three special characters for defining string 
fields: 

# > < 

Table 15-3 in the Reference Section lists all string format characters 
and examples of using each one. The examples below illustrate the 
effects various combinations of these format characters have on string 
item format. 
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The pound sign (#); Each # sign in the format string represents one 
alphanumeric character to ajpear in the output. Including too few # 
signs causes only the specified number of characters to be printed. 

> PRINT USING '##', 'UGANDA' 
UG 

Left angle brackets (<); in a format string cause the indicated number 
of characters from the left-most portion of the datum to be printed. 
Other format characters in the string dictate how many characters will 
be printed as well as the print field positions they will occupy. 

>FRINr USING '<##', 'UGANEA' 

UGA 

>PRINT USING '###', 'YE S' 

YES 

> PRINT USING '<###', 'YES' 

YES 

Right angle brackets (>); cause the specified number of characters from 
the right-most portion of the iton to be printed. Depending on the 
other format string characters, the item may be printed in the first 
character position of the print zone, or forced to another print 
position as shown below. 

>PRINT USING '>##', 'UGANDA' 
NDA 

>PRINT LBING '>###', 'UGANDA' 
ANDA 

>PRINT USING '>##########', 'YES' 
YES 

Placing more than one right or left angle bracket in the same format 
string has the same effect as only one bracket: 

> A$=' UGANDA' 

> PRINT USING '»##', A$ 

A 

X>RINT USING '»', A$ 

A 

>PRINT USING '<', A$ 

U 

>PRINT USING '«#', A$ 

U 

> PRINT USING '<>##', A$ 

U 
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The following program demonstrates several uses of the PRINT USING 
statement. User input is underlined for clarity. 

10 REM EXAMPLE TO ILLUSTRATE PRINT USING 

20 < 

30 INPUT A,B,C 

40 E$= 'STRING' 

50 PRINT USING •<####################', E$ 

60 miNT IBIN3 •>####################', E$ 

70 PRINT 

80 F$='-##.##' 

90 PRINT LBING F$,A,B,C 

100 miNT UBIN3 '$$#####.##', A,B,C 

110 PRINT USING ■>########## EXPRESSION', E$ 

120 REM NOTE RESULT PLACED IN SPECIFIED FIELD 

125 PRINT 

130 INPUT X 

135 PRINT USING '-##.##' ,Sg^ (X) 

: ^UNNH 

!12,13,14 

STOIN3 

STRING 

12.00 

13.00 

14.00 

$00012.00 

$00013.00 

$00014.00 

STRING EXPRESSION 

!46 



6.78 
STOP AT LINE 135 

If a value for A,B or C is too large to fit in the specified field, a 
row of asterisks appears when the relevant PRINT USING statement tries 
to print the over-large value. 
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Example: 

>RUNNH 



11200, 45,7 
STRING 



STRING 



****** 

45.00 
7.00 
$01200. 00 
$00045.00 
$00007.00 

STRING EXPRESSION 

11456 



38.16 
STOP AT LINE 135 



Changing Output Line Lerqth 

By using the MARGIN statement, the length of the output line can be 
altered. Unless a MARGIN statement is included in the program, the 
output line is assumed to be 80 characters. The choice of line length 
depends on the terminal and can be any number of characters from 1 to 
32767. 

A BASIC/VM program can have any number of MARGIN statements. The 
specifications set up by the first MARGIN statanent will remain in 
effect until a subsequent MARGIN statement or a MARGIN OFF statement is 
encountered. MARGIN OFF turns off all previously set margins, leaving 
only the default line length of 80 characters in effect. 

The following program sets the output line length to 45 characters: 

10 REM OOTPUT A MATRIX USING MAT PRINT 

20 MARGIN 45 

30 DIM M{2,6) 

40 MAT READ M 

50 MAT PRINT M 

60 DATA 1,2,3,4,5,6,7,8,9,10,11,12 

70 REM EACH COmh UP TO 9 MEANS TAB 22 CHARACTERS 

80 REM THE NIWBERS AFTER 9 ARE SEPARATED BY 21 CHARACTERS 
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The following results are obtained when the program is run: 

12 3 

4 5 6 

7 8 9 

10 11 12 



This program sets the output line to 40 characters: 

10 REM OUTPUT A MATRIX USING MAT PRINT 
20 MARGIN 40 

30 DIM M(2,6) 

40 MAT READ M 

50 MAT PRINT M 

60 DATA 1,2,3,4,5,6,7,8,9,10,11,12 

Results in: 

1 2 

3 4 

5 6 

7 8 

9 10 

11 12 
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INTRODUCTION 

Program control statements establish the order in v*iich program 
statements are to be executed. These control statements direct program 
branching (e.g., GOTO, GOSUB) , define loops (e.g., FCRHNEXT), transfer 
control to other programs (e.g., CHAIN, COMINP) , and tell a program 
v*ien to stop (e.g., STOP, END). 

There are three categories of control statements: conditional, 
unconditional and loops. Conditional statements transfer program 
control on the basis of a specified condition evaluating to true or 
false. If a condition is true, one set of statements is executed; if 
false, an alternative path is taken. Unconditional statements affect 
execution control independent of conditions established by other 
statements. Loop statements cause a program to loop or repeat a 
section of code until a specified condition is attained. Below is a 
list of statanents within each group. 



Statement Type 



Statements Used 



Unconditional 



GOTO, CHAIN, COIINP 
STOP, END 
GOSUB -RETURN 



Conditional 
Structures 



Loops 



IF-THHvJHilLSE, DO-OOEND 
ON-?GOTO \ 
jGOSUBJ 

fcr-(while)-^ext 

[UNTIL] 
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STATEMENT MODIFIERS 

The statonent modifiers IF, WHILE, UNTIL and UNLESS can be used with 
any executable statement to establish conditions under v\^ich the 
statement should be executed. Unconditional statements can be made 
conditional with statement modifiers, increasing control structure 
flexibility. Below is a list of modifiers and their respective effects 
on companion statanents. The general format of this statenent - 
modifier combination is: 

statement modifier condition [modifier condition]* 

statanent is an executable statement; condition is a locjical 
expression; ^ means repeat as necessary, and modifier is one of the 
following: 

• IF - execute the statenents if condition is true. 

• UNLESS - execute the statanent if condition is false. 

• UNTIL - execute the statements repeatedly while condition is 
false. 

• WHILE - execute the statement repeatedly while condition 
remains true. 

More than one modifier may be included in a statement line. Ihey are 
processed from right to left. 



BRANCHING WITHIN A mOGRAM 

There are two types of unconditional statements: those v^iich cause 
branching within a single program, and those v*iich branch to external 
programs. 

The STOP and END statoinents do not cause branching; instead they 
affect program control by terminating program execution regardless of 
any previously set conditions. 
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Transfer To Another Statanent 

One internal unconditional statement, GOTO transfers execution control 
directly to a specified statement line regardless of the value of any 
condition. The transfer may be either forward or backward. 

Example: 

10 INPUT A 

20 GOTO 50 

30 A = SCR(A+14) 

50 PRINT A, A*A 

60 IF A<20 GOTO 30 

In this program segment, execution control is unconditionally 
transferred to line 50 at line 20. At line 60, program control is 
transferred to line 30, if a certain condition (i.e., A<20) is true; 
if the condition is not met, executions continues with the next 
sequential statement. If a GOTO transfers control to a previous 
statement, a loop can be created as in the following example. Should 
the GOTO, be unconditional, an infinite loop may be established. 

Example: 



100 


PRINT 'INITIAL VALUE' 


110 


INPUT I 


120 


PRINT 'TYPE CHANGE' 


130 


INPUT C 


140 


REM C IS + OR - 


150 


IF C=0 THEM 200 


160 


1=1 +C 


170 


PRINT 'NEW VALUE IS ' , I 


180 


miNT 


190 


GOTO 120 


200 


STOP 



The section between 120 and 190 is repeated until the value of C is 
equal to 0. 

Transfer to Internal Subroutine 

Like GOTO, the GOSUB statement transfers control directly to a 
statement line number. This line is generally the beginning of a 
multi-line subroutine v*iich must always end with a RETURN statement. 
The RETURN statement transfers program control back to the statement 
following GOSUB which called it, and program execution continues. For 
example, the following program conditionally transfers control to a 
subroutine on the basis of a value input from the terminal: 
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Example: 

5 PRINT 'INPUT A VALUE FCR A' 
10 INPUT A 

20 IF A<20 THEN GOSUB 40 
30 GOTO 80 

40 PRINT 'A LESS THAN 20' 
50 A=COS(A) 

50 PRINT 'COSINE OF A =': A 
70 RETURN 

80 PRINT 'FINAL VALUE OF A =': A 
90 END 
> RUNNH 

INPUT A VALUE FCR A 
123 

FINAL VALUE OF A = 23 
> RUmH 

INPUT A VALUE FCR A 
!12 

A LESS THAN 20 
COSINE OF A = .8438539587325 
FINAL VALUE OF A = .8438539587325 

This program illustrates the use of GGSUB-RETURN to set up two 
alternate execution paths. If A is <20, the subroutine is executed; 
if A> or = to 20, control transfers directly to line 80, then ENDs. 

BRANCHING TO EXTERNAL PROGRAMS 

The CQMINP and CHAIN statements direct the flow of a program to 
external command files or progr.ams. 

Control Transfer t o Command File s 

The COMIMP statanent, followed by a quoted argument (e.g., pathname) , 
stops the current program flow, calls the specified external file 
(called command file), to the foreground, then reads and executes the 
commands in it. The command file essentially takes the place of input 
from the terminal. This is useful vstien repeated execution of a series 
of commands is required by one or more programs. The series of 
commands and associated data can be put in a command file and then be 
called by any program as needed. 

The BASIC AM CQ^IINP statanent is much like the PRIMOS command CQMINPUT 
(see Appendix D) . The argument following a COMINP statement must be a 
legal BASIC string. COMINP may also be used as a command, and, as 
such, takes an unquoted string argument. 
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The following program, TESTOUN, uses the CO^INP statenent to call an 
external program, TEST to the foreground. BASICV reads commands from 
this program until instructed by the command CCMINP TTY to resume 
accepting commands from the terminal. This must be the last command in 
the external file. The commands CCMINP PAUSE and ca^lINP CONTINUE can 
be used to temporarily halt and then continue the process of the 
conmand file. 



Example: 



The command file 'TEST' was created under the PRIMOS 
EDITOR and exists in the same UFD as the BASICV program 
'TESTRUN'. Both are listed below: 



TESTRUN 



OK, slist TESTRUN 

GO 

10 PRINT 'TESTRUN' 

20 COIINP 'TEST' 



TEST 



OK, slist TEST 

GO 

10 PRINT 'THIS IS A COMINP FILE, TEST' 

20 INPUT A 

30 PRINT A 

40 IF A < 10 GOTO 20 

50 PRINT 'DONE! ' 

RUN 

1 

2 

3 

4 

5 

6 

7 

8 

91 

COM IMP TTY 



The last command in the file 'TEST' is COMINP TTY 
v^Tich returns program control to the terminal. 
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Example: (continued) 

Ilie following output results when TESTRUN is executed: 



NEW OR. OLDi OID TESTOUN 

>RUNNH 

TESTRUN 

>10 PRINT 'THIS IS A COIINP FILE, TEST' 

>20 INPUT A 

>30 PRINT A 

>40 IF A < 10 GOTO 20 

>50 PRINT 'DONE! ' 

MRUN 

TESTRUN TUE, SEP 05 1978 14:54:31 



THIS IS A CQMINP FILE, TEST 



!l 

1 

12 

2 

•3 

3 

•4 

4 

!5 

5 

!5 

6 

!7 

7 

18 

8 

191 

91 

DONE! 

STOP AT LINE 50 

X:OMINP TTY 

> 



At this point, the BASIC/VM prompt is returned, indicating that it is 
ready to accept input from the terminal. 
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Transferrirg Control to an External Program 

A program external to the one currently in the foreground may be 
executed by including a CHAIN statement in the foreground program. 
When the CHAIN stata:nent is encountered, execution of the foreground 
program is halted, all currently open files are closed, all variables 
and arrays are deallocated, and the specified external program is 
loaded into the foreground and then executed. This external file may 
be either a source or binary (compiled) file. The CHAINED program runs 
until an END or any other control-transfer statement (e.g., CHAIN) is 
encountered. CHAIN is useful in two situations: 



1. 



2. 



If a single program is too large to be loaded into memory at one 
time, it can be divided into more than one program, each one 
being loaded in separately with CHAIN. 



A particular program may be used by several others by 
CHAIN statonents in each calling progam. 



including 



Example: 



Assume that in a directory, there are three programs 
named FROGA, SORT, and OUTPUT respectively. PROGA opens 
and writes data to a file called CCMMON; when the CHAIN 
■SORT' command in PROGA is encountered, SORT is called to 
the foreground and executed. SCRT then writes to a data 
file the values to be used by the file OUTPUT, then 
conditionally CHAINs to OUTPUT. 



10 ! PROGA - MAIN ROUTINE 
100 DEFINE FILE #1 = 'COMMON' 
110 INPUT A, B, C 



ASC SEP 



160 M$ = 'DATA' 



! DATA FILE FOR SORT 



200 WRITE #1, A, L, M$ ! WRITE OUT PARAMETERS FCR SCRT 



999 CLOSE #1 
1000 CHAIN 'SORT' 

BASIC/VM locates SORT, closes PROGA and loads SORT. It then executes 
SORT beginning with the lowest-numbered line, in this case, line 100. 
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100 REM THIS PROG SORTS TATA, CHAINS TO OLTTPUT 

110 DEFINE FILE #1= 'COWON', ASC SEP 

120 READ #1, A, L, M$ ! READ PARAMETERS FCR SCRT 

130 DEFINE FILE #2 =M$ ! OPEN mTA FILE 

• 

500 REWIND #1 

510 WRITE #1, A, L, Z, X$ ! WRITE OUT PARAMETERS 

515 IFOR OUTPUT ROUTINE 

520 IF (A = 1) THEN CI^IN 'OUTPUT' 

If the value of A is equal to 1, the file OUTPUT is brought to the 
foreground and executed. 



CONDITIONAL mOGRAM BRANCHING 

Conditional statanents generally operate in pairs or groups: the first 
statement sets a condition and the second statement provides an 
executable alternative depending on the value of the condition. The IF 
statement, for example, is used in conjunction with other statements 
such as GOTO, THEN, ELSE, and ;D0 to establish conditional branches for 
program control to follow. 

Single Condition Branching: I F Structures 

There are three general formats for the IF statement. These formats 
allow control to be directed to a single statement, to a series of 
statenents (subroutine), or to an alternate statement or subroutine 
depending on whether a conditional expression is true or false. 

For mat 1; sets up two alternate paths for the program to take based on 
vhether the indicated logical expression (condition) is true or false. 



IF expr THEN (stint 

llin-num 



ELSE |stmt-2 
llin-num 



K£gr is a logical expression v^ich is evaluated to true or false; stmt 
is a legal BASIC statement and lin-num is a line number of a statement 
in the program. 

Fo rmat 2: is a simplified version of the previous format, designating 
one line number to v*iich control will be transferred if a condition is 
true. If the expression evaluates to false and no ELSE clause is 
included, the next sequential statanent is executed. statement is 
executed. 

IF expr GOTO lin-num [ELSE lin-num] 
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Parameters are the same as in the previous format. 
Format 3; sets up a multi-branched conditional structure: 
IF log-expr THEN DO 



DOEND 
'ELSE DO" 



.DOEND 

In this structure, if the logical expression ( log-expr ) is evaluated to 
be true, the statements in the DO. ..DO END block are executed. If the 
expression evaluates to false, the statements in the ELSE DO — EXPEND 
block are executed. If no ELSE DO clause exists, the next sequential 
statement is executed whether or not the DO... DOEND block has been 
executed. 



pies 


• 




200 


IF A$ = 'REENTER" 


THEN DO 


210 


M {I,J) = 6 




220 


J = J-1 




230 


DOEND 




240 


ELSE DO 




250 


M {I,J) = K 




260 


J = J+1 




270 


PRINT J 




280 


DOEND 





IF may be used in conjuction with one or more statements, as indicated 
in the program. The series of IF statements first sets up a condition 
specifying a string value for A$. If that condition is true, the 
program is instructed to THEN DO the subsequent statanents until a 
DOEND is encountered. If the value of A$ does not equal the specified 
string, the program is instructed to ELSE DO the subsequent statonents 
until a DOEND is again encountered. A THEN DO or ELSE DO statement is 
always used in conjunction with a DOEND statenent. 
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Branching on Multiple Condition s 

The ra^-GOTO and CN-GOSUB statotient pairs set up one or more conditions 
for control transfer, by means of an arithmetic expression, and a 
corresponding set or list of line numbers to vriiich control will be 
transferred when one of the indicated conditions occurs. Conditions 
are set up by arithmetic expressions which evaluate to integer values. 

Format 1; transfers control to a statenent indicated by a line number 
in the ON-GOTO statement. 

ON expr GOTO lin-num-1 [,lin-num-2 - lin-num-n] 

expr is an arithmetic expression vAiich is evaluated and truncated to an 
integer. If the result is 1, control transfers to the first line 
number listed. If the result is 2, control transfers to lin-num-2 , and 
so forth. 

Example: 

ON I GOTO 100, 200, 450 

I is evaluated and truncated to yield an integer less than or equal to 

the number of statement lines listed with GOTO (i.e., 3). If I is 

evaluated to greater than 3, a GOSUB OVERRANGE error message is 
returned. 

The a^-GOTO combination essentially operates like several IF 
statements. For example, if 500 is the last statement in the program, 
the previous ON-GOTO statement could be replaced by the following 
series of IF statements: 



40 IF I < 1 GOTO 500 

50 IF I > 3 GOTO 500 

60 IF I = 1 GOTO 100 

70 IF I = 2 GOTO 200 

80 IF I = 3 GOTO 450 



500 END 

In this case, the 'GOTO 500' statements are necessary to prevent an 
out-of-range error if the value of I is anything but 1, 2, or 3. 
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Format 2; transfers control to a subroutine beginning at the line 
number chosen depending on the expression value: 

ON expr GOGUB lin-num-l [,lin-nuin-2, .. .lin-num-n] 



RETURN 

expr ^ an arithmetic expression, is evaluated and truncated to an 
integer. Control transfer works as in the OSI-GOTO statement. When a 
RETURN statement is encountered in the subroutine, control returns to 
the statement immediately following the CW-GOSUB statement. For every 
GCBUB executed in a program, exactly one RETURN must be executed. 

LOOP STATEMENTS 

Creating Simple Loops 

The FCR and NEXT statements together create a loop, or a series of 
statements that are executed repeatedly until a previously determined 
condition is met. The FOR statement begins the loop by initializing a 
variable and setting a limit on its value. The NEXT statement ends the 
loop and directs the program back to FOR at v^iich point the variable is 
incremented by one (unless otherwise specified). The FCR-NEXT loop 
continues until the value of the variable has reached the set limit. 
The format is: 

FOR index = start TO end [STEP incr] 



NEXT 

index is a numeric variable representing the loop index. It is 
initialized to start , a numeric expression; the loop is extended until 
the end value for the index is reached, incr represents the increment 
value; default = 1. 

Example: 

15 PRINT 'X', 'X*2', •X"2' 

20 FCR X=l TO 10 

30 PRINT X, X*2, X"2 

40 NEXT X 

50 END 
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This program initializes the value of X to 1 (line 20), PRINTS the 
value, its double, and its square (line 30), returns control to line 20 
and incronents the value of X to 2. The loop continues until the value 
of X equals 10. When this happens, the program skips the NEXT X 
statement line 40 and stops at line 50. 

It is also possible to specify an increment value other than 1. "Ihis 
is accomplished by including STEP in the FCR statement. In the program 
above, the values of X can be £3et from 1 to 100 with increments of 5 as 
follows: 

10 PRINT 'X', 'X*2', 'X"2' 

20 FCR X=l TO 100 STEP 5 

30 PRINT X, X*2, X''2 

40 NEXT X 

In this case, the value of X is initialized to 1, incranented to 6, and 
is incranented by 5 with each pass through the loop until the value is 
equal to or greater than 100. 

Note 

The STEP value may be any value. Also, in 
FCR-loops with statement modifiers, the step size 
is assumed to be zero unless otherwise specified. 

Conditional Loops 

The statement modifiers WHILE and UNTIL may be used with the FOR- NEXT 
statements to place special conditions on loop execution. Instead of 
assigning an end value to index , (the variable v*iich is incremented 
during loop execution), the loop is executed WHILE, or UNTIL a 
specified condition exists. 

WHILE : causes loop execution and variable incrementation to continue 
as long as the specified condition is true. 

Example: 

X = 10 

FOR I = 1 STEP 1 WHILE I<X 

X = X/2 

PRINT I, X 

NEXT I 

STOP 

On each pass through the loop, the value of X is divided by 2. The 
value of I is incremented by 1 as long as it is less than the value of 
X. If no STEP is specified, I would be incremented by zero, or 
unchanged, creating an infinite loop. 
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UNTIL! causes loop execution and variable incrementation to continue 
until the specified condition is met. 

Example : 

10 FOR 1=1 STEP 1 UNTIL J = 1E4 

20 J = J*2 + TAN(I) 

30 NEXr I 

40 END 

On each pass through the loop, the value of J is squared and added to 
the function of I. The value of I continues to be incranented by 1 
until the value of J is equal to 10,000. 
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SECTION 7 
EDITING AND EEBUGGING 



INTRODUCTION 

Errors in a program are basically of three types: syntax errors, which 
are violations of language rules: execution errors, which occur v^en a 
program attempt is illogical or impossible action (sometimes fatal): 
and logic errors, or faults in program logic v*iich produce strange 
results, possibly including program failure. Errors can be detected by 
inspection, compilation and execution, as explained in Section 3. 
Obvious errors in a program can be easily corrected with simple editing 
procedures (discussed in Section 3), or with the editing commands 
detailed in this section. Inconspicuous logic errors v\*iich cause a 
program to execute improperly or not at all may be more difficult to 
detect. The BASICV debugging tools presented here may be of use in 
locating such errors. 



EDITING A BASIC/VM PROGRAM 

In addition to the simple edit features discussed in Section 3, 
BASIC/VM provides commands to perform the following edit functions: 

• deleting one or more statements from a program (DELETE, 
EXTRACT) 

• editing individual lines (ALTER) 

• renumbering statements after edit (RESEQUENTE) 

• determining number of lines in a file (LENGTH) 
Deleting Specific Lines 

The DELETE conmand can be used to remove specific statement lines from 
a prog rain. The format is: 



lELETE lin-num-1 



, . . .( lin-num-n ) 

|lin-num-i - lin-num-n) 



Example: 

DELETE 100, 130-150, 195 
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This deletes line 100, lines 130 through 150 (inclusive), and line 195. 
Extracting Statement Lines 

The EXTRACT command allows the user to delete all lines in a program 
except those specified. The format is: 



EXTRACT lin-num-1 



.|lin-num-n 
(lin-num-i 



lin-num-n 



For example, to delete all lines in a program except 10-50 (inclusive) , 
and line 59, type: 

EXTRACT 10-50, 59 

This will delete all lines in the program except those indicated. 

Editing Within Lines 

Instead of deleting and retyping a line completely, it is possible to 
modify a portion of it. Tlie ALTER command provides a series of 
subcommands which enable editin<3 within lines. The ALTER subcommand 
mode is entered by typing: 

ALTER line-number 

vhere line-number is the line to be modified. A complete list of ALTER 
subcommands can be found in Section 15. Here are some of the more 
useful ones: 

Cx Copies line up to but not including x, v*iere x is any 

character. 

Dx Deletes line up to but not including x. 

F Copy to end of line,. 

I/str/ Insert string (str) at current position. 

R/str/ Retype line with string from current position. 

Q Exit from alter mode. 
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Using ALTER 

The following example shoVNS how the subcommands are used. Ihey are 
entered in response to the ':' prompt and several .may be packed on a 
line without delimiters. ALTER returns the colon after every (CR), 
allowing as many chances as you need to modify the line. Type Q to 
return to BASICA'M command level. 



Examples ; 



1. > ALTER 100 

100 IF X:^ GOTO 230 
: C^lI/>/F 



100 IF X>Y GOTO 230 
:Q 



X^opy up to, but not 
including the = sign. 
Erase 1 character. 
Insert > . 
Copy the rest of the line. 



Another chance to ALTER. 
Leave ALTER 'mode'. 



2. > ALTER 230 

230 PRINT 'TOO LOW 
: M11E3A/HIGH'/ 



230 PRINT 'TOO EIGH' 
:Q 



>Move 11 characters.. 
Erase 3 characters. 
Append HIGH' to the end 
of the line. 



Another chance to ALTER. 
Leave ALTER 'mode'. 
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Fixing a Simple Program 

This example shovs the process of editing, compiling, and executing a 
new program: 

10 ! THIS PROGRAM lEMCNSTRATES THE USE CF AN ACCUMULATCH 

20 ! D= ACCUMUIATED DEPOSITS 

30 !X= DEPOSITS; N= NUMBER CF DEPOSITS 

40 D=0 

45 N=0 

50 READ X 

60 D= D+X ! USE (F LET IS OPTIONAL 

70 N=N +1 • THE AOCLMULATOR 

75 PRINT 'TOTAL AMOUNT OF DE: POSITS TO D^TE IS; $ '; D 

80 PINT 'NUMBER OF DEPOSITS', N 

90 GOTO 50 

100 DATA 14.15, 234.56, 78.90, 12.00, 

X:CMPILE 

80 PINT 'NUMBER OF DEPOSITS', N 

INVALID WORD IN STATEMENT 

>ALTER 80 

80 PINT 'NUMBER CF DEPOSITS", N 

;CII/R/F 

80 PRINT 'NUMBER CF EEPOSITS', N 

iQ 
>COMPILE 

>EXECUrE 

TOTAL AMOUNT OF DEPOSITS TO CATE IS; $ 14.15 

NUMBER OF DEPOSITS 1 

TOTAL AMOUNT OF DEPOSITS TO D^TE IS; $ 248.71 

NUMBER OF IF POSITS 2 

TOTAL AMOUNT OF DEPOSITS CF CATE IS; $327.61 

NUMBER OF re POSITS 3 

TOTAL AMOUNT OF IE POSITS TO CATE IS; $339.61 

NUMBER OF DEPOSITS 4 

TOTAL AMOUNT OF DEBDSITS TO CATE IS; $ 339.61 

NUMBER OF ra: POSITS 5 

END OF EftTA AT LINE 50 

>65 IF X=0 GOTO 110 (110 is END statement) 

110 END (END statenent removes 'END OF D^TA' message) 

X:OMPILE 

>EXECL7rE 

TOTAL AMOUNT OF DEPOSITS TO EATE IS; $ 14.15 

NUMBER OF EEPOSITS 1 

TOTAL AMOUNT OF DEPOSITS TO EATE IS; $ 248.71 

NUMBER OF IE POSITS 2 

TOTAL AMOUNT OF IE POSITS TO EATE IS; $ 327.61 

NU^©ER OF DEPOSITS 3 

TOTAL AMOUNT OF DEPOSITS TO EATE IS; $ 339.61 

NUMBER OF IE POSITS 4 

>85 PRINT (makes printout format neater) 

XTOMPILE 
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>EXBCUTE 

TOTAL AMOUNT OF DEPOSITS TO EATE IS; $ 14.15 

NUNBER OF DEPOSITS 1 

TOTAL AMOUNT OF IE POSITS TO DATE IS; $ 248.71 
NUMBER OF m POSITS 2 

TOTAL AMOUNT OF lEPOSITS TO DATE IS; $ 327.61 
NUMBER OF EE PCS ITS 3 

TOTAL AMOUNT OF EE POSITS TO DATE IS; $ 339.61 
NUMBER OF re POSITS 4 



Determining the Total Number of Statements 

The LENGTH command can be used to determine the number of lines in the 
foreground file. Its format is: 

LENGTH 

Example : 

>LENGrH 
25 LINES 



Renumbering a Program: 

After deleting and inserting statement lines in a program, it may be 
necessary to renumber them in a logical sequence. The RESEQUENCE 
command renumbers a program with default values or with supplied 
values. Any BASICVM program can be renumbered with RESEQUENCE. The 
format is: 

RESEQUENCE [new-start, old-start, new-incr] 

v\*iere new-start is the number with v^^ich to begin renumbering; 
old-start is the line at which to begin the resequence and new-incr is 
the new incranent value with which to continue renumbering. If no 
values are specified, the default values are 100, 1, 10. 
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Example: 

> DELETE 2<d, 40, 80-120 

> LISTNH 
10 PRINT 

30 PRINT 'X", •X'X', •X*X' 

50 LET X=9 

60 PRINT 

70 PRINT X, X'X, X*X 

130 END 

> resequen:e 10, 10, 5 

> LISTNH 
10 PRINT 

15 PRINT 'X', •X'^X', •X'^X' 

20 LET X=9 

25 PRINT 

30 PRINT X, X'^, X*X 

Renumbering begins with number 10, at current program statement 10, in 
increments of 5. 



DEBUGGING A PROGRAM 

Control errors in a program are sometimes difficult to locate. Finding 
and rectifying these errors in a program is called debugging. The 
ddaugging process can be simplified through the use of the commands 
BREAK arri TRACE, and the ON ERROR and PAUSE statements. 

Debug Commands 

The BREAK ON command sets up halts, or breakpoints, at specific lines 
in a program. These breaks return the user to BASICV command level. 
Values being passed within a program can be displayed at these 
breakpoints. Program execution is resumed only if CONTINUE is typed. 
BREAK ON is issued immediately following compilation and prior to 
execution. The format is: 

BREAK (on \ lin-nunr-l[,...lin-num-n] 

[off] 

BREAK OFF, typed prior to re-execution, can turn off any or all 
previously set breakpoints. If no line numbers are specified with 
BREAK OFF, all breakpoints are eliminated. 
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The following source program demonstrates how to use break points to 
cheat at a computer guessing game. 

10 PRINT 'WHAT NU^©ER M I THINKING CF ' 

15 N=INT (50*RND (0 )+l ) 

20 FOR C = TO 10 

30 INPUT X 

50 IF X<N GOTO 90 

60 IF X>N GOTO 110 

70 PRINT 'RIGHT, ANOTHER! ' 

80 GOTO 140 

90 PRINT "TOO LOW 

100 GOTO 120 

110 PRINT 'TOO HIGH' 

120 NEXT C 

130 PRINT 'TIME IS UP. ANOTHER' 

140 INPUT A$ 

150 IF t£FT(A$,l)='Y' THEN 15 

160 STOP 



X:OMPILE 



> BREAK ON 50 
>EXECUrE 



WHAT NUMBER AM I THINKING OF 
! 27 

BREAK AT LINE 50 
>FRINT N 
41 
>X=41 



X:ONTINUE 

RIGHT, ANOTHER! 

!N 

STOP AT LINE 160 

> eREAK OFF 50 

The program is instructed to stop at line 50. The user finds out what 
the number is ( HRINT N) and sets an answer (X) equal to that number, in 
this case, 41. Program execution is resumed with the CONTINUE command 
at vAiich point the system responds that the correct answer has been 
given. When the answer 'N' (for 'NO') is given to the 'RIGHT, 
ANOTHER!' prompt, the user is returned to conmand level. 'BREAK OFF 
50' indicates that when the program is run again, no break will occur 
at line 50. 
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Inserting Program Halts 

The PAUBE statement acts as an executable BREAK. It is used in 
conjunction with CONTINUE. I'frien the program halts at the line number 
on vvhich the PAUBE statement appears, the words "PAUBE AT LINE x;, 
\A\ere x is the appropriate line nuntoer, are displayed, indicating the 
temporary halt. CCNTINUE is ti^ed v*ienever the user wishes to resume 
the program after a breakpoint,. 

Example: 

10 PRINT 1 

20 PAUSE 

30 PRINT 3 

40 END 

>RUNNH 

1 

PAUBE AT LINE 20 

XTONTINUE 

3 

Tracing Statement Execution 

The "TOACE ON command is issued immediately after COMPILing, and 
immediately prior to EXECUTing a program. It is useful in tracing the 
path of program execution, thereby expiating the debugging process. 
The line number of each statemcjnt executed is displayed in brackets, 
e.g., [120]. For example, if a specified condition is met, a GOTO or 
GOSUB statement will be exec:uted, and its line number will be 
displayed. When program execution terminates, type TRACE OFF, and the 
program can be re-executed normally. 
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Example : 



5 PRINT 'INPUT A VALUE FOR A' 

10 INPUT A 

20 IF A<20 THEN GOSUB 40 

30 GOTO 80 

40 PRINT 'A LESS THAN 20 ' 

50 A=COS (A) 

60 PRINT 'COSINE CF A =': A 

70 RETURN 

80 PRINT 'FINAL VALUE O?" A =': A 

90 END 

XTOMPILE 

> TRACE ON 

> EXECUrE 

[5] 

INPUT A VALUE FOR A 

[10] 
!13 
[20] 
[40] 

A LESS THAN 20 
[50] 
[60] 

COSINE OF A = .9074467814502 
[70] 
[30] 
[80] 

FINAL VALUE CF A = .9074467814502 
[90] 

> TRACE OFF 
>EXECUrE 

INPUT A VALUE FOR A 
!23 
FINAL VALUE OF A = 23 

Notice that after TRACE OFF was typed, the program executed without 
line number display. 
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TRAPPING EXECUTION ERRCRS 



There are several ways to set up error traps within a program. The CN 
ERROR statement establishes a line number to v\hich control will be 
transferred v\*ien a run-time error occurs. Variation of the Oti ERROR 
statement provides for redirection of program flow if an I/O error 
occurs on a specified unit. For example, if invalid data is input, 
control can be transferred to a statement that will print out an 
appropriate error message. The format is: 

ON ERRCR [#unit] GOTO lin-num 

The # unit option is used in trapping I/D errors on a unit previously 
opened by a ffiFINE FILE statement. See Section 8 for details. 

Turning Off Error T raps 

The ERROR CFF statement can be employed to cancel all error traps 
established by ON ERRCR GOTO statements. The format is: 

ERROR OFF 

The example below uses the liRRQR CFF functionality to turn off error 
trapping after a certain point in the program. 

Identifying Locations and Codes of Errors 

The following special variables and functions can be used to identify 
the location and nature of errors trapped: 



ERR 



ERL 



a variable set to the code number of the trapped 
error. 

a variable set to the line number at wfiich an 
error occ:urred. 



ERR$ (num-expr) a function Wiich outputs the text of the error 
message associated with an error code, 

represented by nim-expr . 

A complete list of run-time error codes and corresponding messages can 
be found in Appendix C. 
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Using Error Traps 

The following ex;aiple uses several of the error trap features presented 
above: 

110 INPUT 'FILENAIviE ', A$ 

100 ON ERROR GOTO 1000 

120 DEFINE FILE #1 = A$ 

130 DEFINE FILE #2 = 'OUTFILE ' 



500 ERROR OFF 



990 STOP 

1000 PRINT ERR$(ERR); 'AT LINE' : ERL 

1010 CLOSE #1,#2 

1020 STOP 

This program directs control to line 1000 if an error occurs between 
line 110 and line 500. Line 1000 prints the text of the error via the 
ERR $ (ERR) function. It also identifies the error line via the ERL 
function. Line 1010 instructs the program to close the opened files. 
The program then stops at line 120. If no error occurs, the program 
will stop at line 990. If the ERROR OFF statement is omitted, the ON 
ERRCR will be effective throughout the entire program. 

The statement to which control is transferred may also identify the 
error by its code, and then instruct the program \hat to do next. 

For example: 

IF ERR = 13 THEN DO 

PRINT LIN (2) , 'END OF TEST ' 

END 
DOEND 

indicates that if an END OF D^TA error, (error code 13), has occurred, 
the message 'END OF TEST' will be printed, and the program will stop. 
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INTRODUCTION 

BASICAM utilizes all of the file types provided by the File Management 
System (BWS) of PRIMOS. These file types, and the type-codes by which 
they are identified, are: 

• ASCII sequential (ASC, the default) 

• ASCII sequential separated (ASCSEP) 

• ASCII sequential line-numbered (ASCLN) 

• ASCII direct access (ASCCA) 

• Binary sequential (BIN) 

• Binary direct access (BINDA) 

• Segment directory (SEGDIR) 

• Multiple Index Data Access (MIDAS) 

Because these files are all created under the auspices of FMS, file 
compatibility between BASICV programs and programs written in other 
Prime languages (e.g., COBOL, interpretive BASIC, FORTRAN) is assured. 

Implementation of these data files in BASIC/VM programming is known as 
'file handling'. File handling usually involves opening (or defining) 
a file, writing data to the file for storage, and reading, or 
retrieving, the data when needed. 

The BASIC/VM default file type, ASCII sequential, provides storage and 
access methods suitable for most prograitming needs. The seven other 
file types offer alternate features which may optimize storage 
efficiency and/or program execution when properly utilized. 

This section describes the available file types, their features, 
possible uses, and the statements needed to perform the routine file 
handling operations, listed below. Only the basic information needed 
to use these files in routine BASICAM prograitming is contained in this 
section. Users requiring more details on file properties, features and 
uses should consult Appendix E, Advanced File Handling. 
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Operation 

• evening a file 

• Writing data to a file 

• Examining data storage 

• Reading data from a file 

• Moving the file pointer 

• Updating record data 

• Trapping errors during file 
operations 

• Write a matrix to a file 

• Reading data into a matrix 

• Closing a data file 

• Deleting a data file 

OPENING A EATA FILE 



Statement Used 

EEFINE 

WRITE 

TYPE, SLIST 

READ[*], READLINE 

POSITION, REWIND 

WRITE 

ONJERRO^I GOTO 

lEND I 
MAT WRITE 
MAT READ[*] 
CLOSE 
REPLACE 



The DEFINE FILE statement is the key to all data file operations in 
BASIC/VM. DEFINEing a file is relatively simple but involves a number 
of concepts v^ich are important to all file handling operations. The 
DEFINE process does several important things including: 

reserving buffer space in memory for data storage 

naming a file 

assigning a particular file type to the file 

optionally changing the record size of the file 

restricting I/O operations to reading or writirxg 

The DEFIN E Statement 

The format of the DEFINE statement is: 

DEFINE READ FILE #unit = filename [, type-code] [, record-size] 
APPEND 

The parameters are discussed below. 
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File units 

PRIMOS requires some buffer space in j*iysical memory to serve as an 
intermediary storage area for each opened file. These buffers are 
called file units. To open or define a file in BASIC/VM, a correlation 
must be established between a filename and a file unit nunber. The 
file unit number is specified by the unit parameter, a numeric 
expression with a range of 1 to 12. The number assigned to the file is 
used as a sort of shorthand reference to the file throughout subsequent 
file operations. The # sign is a required part of the statement 
proper, and signifies that a data file is to be opened on the specified 
unit. 

Up to 12 file units may be opened and active at one time per user in 
the BASICV subsystem. If an attanpt to open more than 12 units is 
made, an error message will be displayed. 

Filename 

Each data file opened must be assigned a name, as represented by 
filename , a legal BASIC string parameter. 

Type-code 

As mentioned in the introduction, each file type available under PMS 
has a particular type-code by v^ich it is identified to BASIC/VM and 
PRIMOS. All file types, theTr corresponding type-codes, and important 
features, are listed in Table 8-1. Note that specification of 
type-code is optional. The default type is ASCII sequential (ASC) . 

Record-size 



Items in a data file are stored in logical units called records . The 
size of a record determines how many characters it can contain. This 
character limitation is measured in words at the rate of 2 characters 
per word. The default record-size is 60 words, or 120 characters. The 
record size of a file may be increased or decreased by specifying the 
appropriate numeric value for the record-size parameter. record-si ze 
is specified in number of words per record, as opposed to number of 
characters. The minimum record-size is four words for every file type 
except MIDAS. The maximum record size is 512 words. 

In some types of files, all records in the file are fixed to the 
specified number of words, or to the default size, if the record-size 
parameter is omitted. Records in this type of file are called 
fixed-length records. Each record in the file is the same length, even 
though each record may not contain the same nunber of data characters. 
Other types of files have variable-length records, in which each record 
is only as long as the data it contains. 
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Access Restrictions 

The optional arguments, READ and APPEND, place restrictions on I/O 
operations that can be peformecJ on a file. The READ argument allows 
the file to be read from only. No data can be written to the file 
while the restriction is in effect. The APPEND argument postions the 
read pointer to the bottom of the file v^en it is opened. Each file 
has a pointer v^ich keeps track of the record currently positioned to 
for reading or writing. This restriction allows data to be written to 
the bottom of the file only, unless the pointer is repositioned. 



REV. 



PDR3058 



FILE HANDLING 



Table 8-1. File Type-Codes 



Access 
Type -Code Method 

ASC SAM 

(default) 



ASCSEP SAM 



ASCLN 



SAM 



ASCEA 



nm 



BIN 



SAIVI 



BINDA 



SEGDIR 



EftM 



SPECIAL 



Contents 

ASCII data, formatted like terminal output, 
using BASICV PRINT conventions, e.g., 
commas, colons and semi-colons, all dictate 
the appropriate number of spaces to be used 
as data delimiters. Records variable-lerqth 
and easily inspected. 

ASCII data stored with commas inserted 

as data delimiters. Data are stored 

and read back exactly as entered. 

Records fixed-length, accessed sequentially. 

ASCII data with comma delimiters, 

and line numbers inserted in increments 

of 10 at the start of each record. 

Designed to be edited at BASICV command level. 

Similar to ASCSEP. Records fixed-length 
and blank-padded as necessary. Direct access 
method used for quick, random access to 
any record in the file. 

Data storage transparent to user. 
Records are fixed-length, accessed sequentially. 
String data stored in ASCII code: numeric data 
stored in four-word floating-point form. 
Provide maximun precision and compactness of 
numeric data, but cannot be inspected by TYPE etc. 

Same as BIN but direct access method 
is used for random record access. 
Records not data-filled are zeroed out. 

Identifies file as a segment directory. 
Subordinate files, identified by nunber, 
may be SAM, DAM or other SEGDIR files. 
An additional DEFINE is required 
to access a subordinate file. 



MIDAS SPECIAL Multiple Index Data Access files. 

Created by Prime-supplied MIDAS utilities. 
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ACCESS METHODS 



Retrieval of data from files is accomplished by one of the four access 
methods provided by BASICV and i'"MS: 

• Sequential Access Method (SAM) 

• Direct Access Method (DAM) 

• Segment Directory Access Method (SEGDIR) 

• Multiple Index Data Access Method (MIDAS) 

Each access method corresponds directly to a particular file structure. 
These structures are illustrated in Figure 8-1. For a representation 
of MIDAS file structure, refer to Reference Guide, MIDAS or the 
Subroutine Reference Guide. 

Both file structures and access methods are built into the FRIMOS 
operating system. Access methocis determine how individual file records 
are identified and retrieved from their storage place on disk. The two 
fundamental access methods , sequential (SAM) and direct (DAM) , are 
explained below. SEGDIR and MICftS access methods expand upon SAM and 
DAM features and are discussed in the latter part of this section. 

The remainder of this section is divided into four parts. Each part 
describes the statements usecl in dealing with files of a particular 
access type. More details on the properties of each file type, as well 
as extended examples of their use, can be found in Appendix E, Advanced 
File Handling. In particular, the properties of the default type, ASC, 
are discussed at length and then compared with the corresponding 
features of other ASCII file types. Users considering serious file 
handling should investigate the differences among file types before 
working with data files. 
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FIXED LENGTH RECORDS: 
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SEGMENT DIRECTORY 



DIRECTORY CONTAINS POINTER 
FILES WHICH REFERENCE 
DATA FILES (DAM/SAM) 



1 
2 
3 
4 



DATA FILE 2 (SAM) 



1 
2 
3 
4 
5 



DATA FILE 6 (DAM) 



SEGDIR ORGANIZATION 



Figure 8-1. File Structures 
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Sequential files can be opened and manipulated by the following set of 
statements . 

Statements Used in Sequential Access 



DEFINE 



Cpens, names and assigns a file type, either ASC, 
ASCSEP, ASCLN or BIN and associates it with a file 
unit. 



WRITE, 
WRITE USING 



Writes data records of the appropriate type to the 
opened file and advances the pointer to the next 
record after each WRrrE. 



READ [*] Reads the record at the current pointer position 
READ LINE and advances the pointer to the next record. Must 
rewind in order to READ after a WRITE. 



REWIND 



Returns the pointer to the first record of the 
file. 



ON END 



Determines the action to be taken if the pointer 
reaches the end of the file. 



CLOSE 



Makes sure the file is properly restored to disk 
and frees the file unit for other use. 



Opening a File 

The first step in any file handling operation is to open or DEFINE a 
file. Any of the file types listed in Table 8-1 can be opened with 

DEFINE. 

The type-codes which define SAM files are: ASC, ASCSEP, ASCLN and BIN. 
For example, the following statement opens an ASCII sequential file 
with comma separators (ASCSEP file) : 

DEFINE FILE #1 = 'ASCSEP', ASCSEP 

Adding Data To SAM Files 

Data values are written to a CGFINEd file one record at a time with 
successive WRITE statements. Each successive WRITE operation moves the 
pointer to the next sequential record, where it awaits the next 
instruction. Each new WRITE statement adds the indicated data to a new 
record in the file. 
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Below is an example of writing data to each sequential file type. By 
TYPEing each file (using the TYPE command) , the data storage patterns 
of each file type (except binary) can be inspected. 

For more details on data storage in each file type, refer to Appendix 
E. 

Example: 

>DEFINE FILE #1 = 'A' 

>DEFINE FILE #2 = 'B ' , ASCSEP 

>DEFINE FILE ff3^~'C"V7 feCLN 

> DEFINE FILE #4 = 'D', BIN 

>A=12 

> B^^^HELLO! ' 

>WRITE #1,A 

>WRITE #2, A 

>WRITE #3, A 

> WRITE #4, A 

>WRITE #1,B$ 

> WRITE #2,B$ 

>WRITE #3,B$ 

>WRlfET4,B$ 

> CLOSE #1,2,3,4 

> TYPE A 

12 

HELLO! 

>TYPE B 

12, 

HELLO! , 

>TYPE C 

10 12, 

20 HELLO! , 
>TYre_D 
J1ELL0!> 

WRITEing Formatted Data to a File 

The WRITE USING statement is similar to PRINT USING (see Section 6) in 
that it enables the formatting of data according to a format string. 
Format strings are composed of special characters which are listed in 
Table 15-2 and Table 15-3. A summary of PI^INT USING features can also 
be found in Section 15. Formatted data can be written to any type of 
ASCII file. An attanpt to write formatted data to a binary file will 
generate an error message. 
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The WRITE USING statement has two formats: 

WRITE # unit LBING forniat-string, item-1 [,...item-n] 
WRITE USING format-string., # unit, item-1 [,...item-n] 

In either case, the f ormat-stri ng may be nuneric or string, deperx3ing 
on the data , (item-1 - item-n) ,, to be formatted . 

Example: 

>DEFINE FILE #1 = 'EXMPLE ' 
>WRITE #1 USING '$###.##', 120 
> WRITE #1 USING '<#####', 'FUNNY' 
>WRITE #1 USING '>#####', 'FUNNY' 
>WRITE #1, 120 ~ 



>WRITE 


#1, 


•FUNNY' 


x:edse 


#1 




>TYPE EXAMPLE 


$120. 0e 


1 




FUNNY 






FUNNY 






120 






FIl^Y 







In the first WRITE USING statement, a numeric value is formatted with a 
decimal point, two trailing zeroes, and a dollar sign prior to the 
left-most digit. The pound signs (#) indicate how many digits are to 
be output. If the value was too large for the format string to 
accomodate, a string of asterisks WDuld ajpear in the output. For 
example : 

WRITE #1 USING •$###.##', 12000 

REWIND #1 

READ #1, A$ 

PRINT A$ 
******* 

The second WRITE USING statement left- justifies a string datum in the 
file with by using the '<' symbol. The third statanent writes the same 
item with right- justification by using the '>' symbol. . The data 
written to a file with WRITE LBING are stored in the format specified 
by the format string as shown. 

READirq SAM Files 

Data are retrieved from SAM files with the READ statement, as shown in 
the previous examples. The READ statement has two variations, READ* 
and READLINE. All three are used to obtain information stored in a 
data file. Specific examples of READing each file type are included in 
Appendix E. 
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REWINDing The Fi le Pointer 

In order to READ a record above the record to v*iich the pointer is 
currently positioned, a RBi^IND statatient can be used to reposition the 
pointer to the top of the file. Records can not be positioned to at 
randan in sequential files. 

In sequential files, READs cannot take place immediately after a WRITE 
to the same file. An attempt to do so generates the following error 
message: 

READ AFTER WRITE ON SEQUENTIAL FILE 

In order to READ after a WRITE, the file pointer must be returned to 
the top of the file with REWIND. An alternative is to CLOSE the file, 
re-open it and then READ sequentially until the desired record is 
reached. When a file is opened, the pointer automatically positioins 
to the top of the file unless otherwise instructed, as with the 
'APPEND' option of the EEFINE command. 

Example: 

>DEFINE FILE #1 = 'ASC 



>WRITE #1, 12 

>READ #1, A 

READ AFTER WRITE ON SEQUENTIAL FILE AT LINE 

>REWIND #1 
>READ #1, A 
>FRINT A 
12 

x:lose #1 

> define f ile #1 = 'asc' 

> READ #1,A 
>PRINT A 
12 

x:lose #1 



The READ* Statement 

A variation of the READ statement, READ*, forces the file pointer to 
remain at the current record after a READ is ccmpleted, rather than 
moving it to the next sequential record. This is advantageous v\*ien 
performing a series of READs on a single record. If a record contains 
several values which are to be retrieved individually during successive 
READS, the pointer can be 'put on hold' at the current record, enabling 
another READ of this record to be performed. The details of READ* are 
illustrated in the example below. Some points to keep in mind are: 



- 11 March 1979 



SECTION 8 PDR3058 



• If a READ with no * option follows a READ*, the pointer 
automatically advances to the next record. 

• If a READ* follows a READ*, the current record is read until 
all the given variables are satisfied. If necessary, the 
pointer then advances to the next record to satisfy any 
remaining variables. 



Example ; 



10 DEFINE FILE #1= 'ASC*' 

20 DEFINE FILE #2 = 'SEP*', ASCSEP 

30 DEFINE FILE #3 = 'LN*' , ASCLN 

40 DEFINE FILE #4 = 'BIN*' , BIN 

50 REWIND #1,2,3,4 

60 READ A,B,C,D,E,F 

70 DATA 10,20,30,40,50,60,70 

80 PRINT 'FIRST READ WITHOUT *' 

90 PRINT 

100 FOR N=l TO 4 

110 WRITE #N,A,B,C 

120 WRITE #N,D,E,F 

130 NEXT N 

140 REWIND #1,2,3,4 

150 FOR N= 1 TO 4 

160 PRINT 'THIS IS FILE ON UNIT #': N 

170 PRINT 'BEGIN READ WITHOUT *' 

180 READ #N,A 

190 PRINT A 

200 PRINT 

210 READ #N,B 

220 PRINT B 

230 PRINT 

240 REWIND m 

250 PRINT 'NOW READ WITH *' 

260 READ * #N,A 

270 PRINT A 

280 PRINT 

290 READ * #N,B 

300 PRINT B 

310 PRINT 

320 REWIND iM 

330 PRINT 'END OF READ ON UNIT #':N 

340 PRINT 

350 NEXT N 

360 CLOSE #1,2,3,4 

370 PRINT 'END OF TEST' 

380 END 

>RUNNH 

FIRST READ WITHOUT * 
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THIS IS FILE ON UNIT # 1 
BEGIN READ WITHOUT * 
102030 

405060 

NOW READ WITH * 
102030 

405060 

END OF READ ON UNIT # 1 

THIS IS FILE ON UNIT # 2 
BEGIN READ WITHOUT * 
10 

40 

NOW READ WITH * 
10 

20 

END OF READ ON UNIT # 2 

THIS IS FILE ON UNIT # 3 
BEGIN READ WITHOUT * 
10 

40 

NCW READ WITH * 
10 

20 

END OF READ ON UNIT # 3 

THIS IS FILE ON UNIT # 4 
BEGIN READ WITHOUT * 
10 

40 

NOW READ WITH * 
10 

20 

END OF READ ON UNIT # 4 

END OF TEST 
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>TYPE ASC* 

10 20 30 

40 50 60 

>TYPE SEP* 

10,20,30, 

40,50,60, 

>TYPE LN* 



10 10,20,30, 
20 40,50,60, 



The READLINE Statement 

HEADLINE is actually a variation of the READ statement that allows the 
reading of an entire ASCII file record, including commas, colons, 
semi-colons and spaces, as one data item. This is especially useful 
v^rfien default ASCII or ASCSEP files contain data with internal contnas. 
READLINE ignores commas as data delimiters (tnlike optionless READs) . 
Thus conma-containing strings will not be broken up by READLINE. For 
example, if a record in an ASCII file opened on unit #1 contained the 
following values: 

MARCUS WEL8Y, M.D. 
READ #1, A$ would return: 

MARCUS WELBY 
READLINE #1, A$ would return: 

MARCLG WEIBY, M.D. 

READ vs. READLINE 

The following example emphasizes the differences between READ and 
READLINE for all SAM file typss. Note however, that READLINE will not 
work on binary files. 



10 DEFINE FILE #1 = 'ASCRL' 

20 DEFINE FILE #2 = 'SEPRL', ASCSEP 

30 DEFINE FILE #3 = 'LNRL', ASCLN 

40 DEFINE FILE #4 = 'BINRL' , BIN 

50 READ A$,B,C$ 

60 DATA 'WELBY, MARCUS, M.D. ; LIC.NO. :', 123001, 'PHONEY' 

70 FOR N=l TD 4 

80 WRITE #N, A$,B,C$ 

90 NEXT N 

100 REWIND #1,2,3,4 

110 FCR I = 1 TO 4 

120 PRINT 'READ FCR FILE ON UNIV #": I 

130 READ #1, A$ 
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140 PRINT 

150 PRINT A$ 

160 REWIND # I 

170 PRINT 

180 PRINT 'READLINE FOR FILE ON UNIT #': I 

190 PRINT 

200 READLINE #1, A$ 

210 miNT A$ 

220 PRINT 

230 REWIND # I 

240 NEXT I 

250 CLOSE #1,2,3,4 

>RUNNH 

READ FOR FILE ON UNIT # 1 

WELBY 

READLINE FCR FILE ON UNIT # 1 

WELBY, MARCUS, M.D.; LIC.NO. : 123001 raONEY 

READ FOR FILE ON UNIT # 2 

WELBY 

READLINE FCR FILE ON UNIT # 2 

WEEBY, MARCUS, M.D.; LIC.NO. : ,123001, PHONEY, 

READ FCR FILE ON UNIT # 3 

WELBY 

READLINE FOR FILE ON UNIT # 3 
WEIBY, MARCUS, M.D. ; LIC.NO. : ,123001, PHONEY, 

READ FOR FILE ON UNIT # 4 

WELBY, IVIARCUS, M.D. ; LIC.NO.: 

READLINE FOR FILE ON UNIT # 4 

ILLEGAL OPERATION ON BINARY FILE AT LINE 200 



The error message displayed indicates that READLINE is not a legal 
operation on a binary file. 
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Reach ing EM3 OF FILE 

V*ien the file pointer reaches the end of a file during a READ, an END 
OF FILE error message is generated. "This causes program execution to 
terminate abruptly. To avoid this, include an ON END statement to 
transfer control to another program line where an appropriate action 
will be taken. For example, the following ON END statement transfers 
program control to a statement v>*iich closes the file unit: 

10 ON END #1 GOTO 200 



200 CLOSE #1 

Trapping Errors 

Errors that occur during data file access can be trapped with the ON 
ERRCP- GOTO statement, discussed in Section 7, or with the ON END #unit 
- GOTO statement, designed specifically for data files. If the end of 
the file is reached during a file READ, for example, an error message 
will be generated, and the program or current operation will be halted. 
Inclusion of the ON END statement in a program will eliminate unwanted 
program halts by transferring control to another program line or by 
performing an appropriate action. 

This statement is generally placed near the beginning of the program. 
It can be used for both SAM and DAM files, and is especially helpful 
lA^en doing multiple READs from a binary file v*iose contents are not 
easily monitored. 

Example: 

10 DEFINE FILE #1 = 'ENDl', ASCSEP 

20 ON END #1 GOTO 90 

30 WRITE #1, 'LAND VALUES AS OF 1975' 

35 WRITE #1, 'CALIFCRNIA' ,' NEW YORK' 

40 REWIND #1 

45 READ #1, A$ 

50 READ #1,B$ 

55 READ #1,C$ 

60 PRINT A$ 

65 roiOT 

70 PRINT B$,C$ 

75 GOTO 120 

90 PRINT 'END OF FILE REACHED' 

100 REWIND #1 

105 READ #1,A$,B$,C$ 

110 GOTO 50 

120 CLOSE #1 

>RUNNH 

END OF FILE REACHED 

LAND VALUES AS OF 1975 



REV. 8-16 



PDR3058 FILE HANDLING 



CALIFCeNIA NEW YCRK 

STOP AT LINE 120 

>!IF WE REMOVE THE ON END STATEMENT, WE'RE IN TROUBLE 

>20 

>RUNNH 

END OF FILE AT LINE 55 



CLOSEing a File 

When access to a file is completed, it is a good idea to CLDSE the 
file. This ensures its proper restoration to disk, and releases the 
file unit on which it was opened for other use. If the file is not 
CLOSEd, it may be lost or truncated when a BREAK or QUIT occurs. A 
single CLOSE statement can close one or many file units which have been 
opened. Example: 

CLOSE #1,2,3 

Opening a Tempor ary File 

A temporary or SCRATCH file may be opened with a short form of the 
DEFINE statement: 

DEFINE SCRATCH FILE #unit [, file-type] [, record-size] 

The indicated unit is opened as a temporary file of any type except 
MIDAS. When the unit is CLOSEd, the file is deleted. _ No filename need 
be spec i fed. The record-size can be optionally modified. 
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The statements used in dealing with DAM files are identical to those 
previously discussed under SAM file handling. The important exception 
is POSITION. The following is a list of all available DAM file 
handling statements. 

Statements used in Direct Access 



Statement 



Description 



DEFINE 



Opens, names and identifies a direct access file 
as ASCII (ASCEA) or binary (BINDA) ; associates 
it with a file unit and optionally sets the 
record size (in words). 



WRITE, WRITE USING 



POSITION 



READ[*] ,READ LINE 



REWIND 
ON END 



Writes data records to the file opened on 
specified unit; advances pointer to next 
sequential record. 

Moves the file pointer to any record in the file. 
Records are positioned to by nunber. 

Reads values fran record to v^ich pointer is 
currently positioned; advances pointer to the 
next record unless * is specified. Random reads 
can be done by POSITIONing the file pointer. 

Returns pointer to first record (top) of file. 

Establishes action to be taken when pointer 
reaches the end of the file. 



CLOSE 



Closes file to reading and writing 
file unit for other use. 



and releases 



Defini ng DAM Fil es 

Direct access files are opened in the same manner as are SAM files. 
(See the DEFINE statement, above.) Records in a DA file can be set to 
a value larger or smaller than the default of 60 words (120 characters) 
when the file is first defined. The minimun is 4 words: the maximum 
512. The record size of a EAM file is fixed to the supplied value, if 
given, or to the default value. This value remains in effect for every 
record added to the file. Details on adjusting the record size of a DA 
file can be found in Appendix E. 



REV. 



- 18 



Pm3058 FILE HANDLING 



Direct access files are either ASCII or binary, as are sequential 
files. Direct access files are identified in BASIC/VM by the 
type-codes ASCDA or BINDA. 

The following statement defines or opens an ASCII direct access file 
with a record size of 35 words (70 characters): 

I^FINE FILE #1='DIRECT', ASCDA, 35 

Writirq Data To DAM Files 

Data are stored in ASCDA files just as they are in ASCSEP files, i.e., 
with comma delimiters. Commas are inserted as internal data markers in 
both types, so string values containing commas will be broken up. 
Sanicolons, conmas and colons used as delimiters in WRITE statements 
are ignored, as shown below: 

10 DEFINE FILE #1 = 'ASCDA', ASCDA 

20 DEFINE FILE #2 = 'BINDA', BINDA 

30 READ A$,B,C,D 

40 DATA 'TRIANGLE DIMENSIONS ' , 12, 13, 14 

50 WRITE #1,A$ 

60 WRITE #1,B;C;D 

70 WRITE #2, A$ 

80 WRITE #2,B,C,D 

90 CLOSE #1,2 

>RUNNH 

STOP AT LINE 90 

>TYPE ASCDA 

TOIANGLE DIMENSIONS, 

12,13,14, 

>TYPE BINDA 

<TRIANGLE DIMENSIONSF 1976 



Random Access to DAM File Records 

The major advantage of DAM files over SAM files lies in their record 
access flexibility. The file pointer can be moved to any record in the 
file with the POSITION statement. Records are positioned to by nunber. 
The number corresponds to the position of the record relative to the 
top of the file; i.e., record number one is at the top of the file, 
and so forth. The data in the currently positioned record can then be 
obtained with a READ statement. 
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The LIN#(unit) function can be used in CAM file access to check the 
actual record number to v^^iich the pointer is positioned. Instead of 
returning a line number as it does in ASCLN files, LIN #(unit) returns 
the number of the record in the file. 

In the following example, a file is DEFINEd and data are added to it. 
The actual file contents are inspected by TYPEing the data file. Next 
the file is re-opened for READ access only and data are retrieved with 
POSITION and READ. 



Example: 



>10 DEFINE FILE #1 = 'ASCm2', ASCI:A,30 

>20 WRITE #1, 'THIS IS THE INFORMATION FOR ROBERT SNCRK ' 

>30 WRITE #1,'NA|V1E: ROBERT SNORK; TITLE: OPTHAMOLOGIST' 

>40 WRITE #1, 'ADDRESS: 12 MYOPIC LN, OCULAR, WISCONSIN' 

>50 CLOSE #1 

>RUNNH 

STOP AT LINE 50 

>TYPE ASCDA 

THIS IS THE INFORMATION FQ^ ROBERT SNORK, 

NAME: ROBERT SNCRK; TITLE: OPTHAMOLOGIST, 

ADDRESS: 12 MYOPIC LN, OCULAR, WISCOMSIN, 

>! 

>!Open a READ only file 

>DEFINE READ FILE #1 = 'ASC:DA2', ASCDA 



>POSITION #1 TO 


3 


>FRINT 


LIN#(1) 




3 
>READ 


#1,C$ 




>PRINT 
ADORES: 
>PRINT 


c$ 

S: 12 MYOPIC 
LIN#(1) 


4 

>READ 


#1,A$ 





LN 



END OF FILE AT LINE 



In this example, the record size was set to 30 words (60 characters) . 
In direct access, the file pointer scans throigh the file until the 
beginning of the desired record has been reached. Vne pointer 
determines the actual location of this record by counting the number of 
characters it has to bypass in order to reach it. The pointer knows 
how many characters are in each record, so it counts, in this case 2 
times 50 characters, or 120 characters, to reach the third record. The 
pointer will now be at character 121, which begins the third record. 
The LIN# function clearly indicates that the pointer is now at the 
third record. After the READ is done, the pointer is at record #4, as 
indicated by the LIN #(unit) function. Note that when opening a file 
for READing only, the record size need not be given; however if an 
incorrect record-size is specified, the error message, DA RECORD SIZE 
ERROR AT LINE is returned. 
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Reading DAM Files 

DAM file READS are done in the same manner as are SAM file READ, i.e., 
READ, READ* and READLINE work in direct access just as they do in 
sequential access. Each READ statement advances the file pointer to 
the next sequential record when the READ has been completed. READ* 
holds the pointer at the current record until all the values specified 
in the next READ statanent are satisfied. In ASCDA files, READLINE 
returns all the values in a record as one datun, commas, semi-colons, 
etc, included. 

If a file has been previously DEFINEd and written to, it can be opened 
and restricted to READ or APPEND access by using the READ or APPEND 
options of the DEFINE statement, as in the previous example. 

Error T rapping in DAM Files 

END OF FILE errors, as well as other execution mishaps, can be trapped 
via the ON END and ON ERROR statements discussed earlier under SAM file 
handling. These statements are applicable to diract access files as 
well as sequential files. 

CLOSEing a CAM File 

Direct access files are closed in the same manner as are SAM files. It 
is a good practice to close all data files when access to them has been 
completed. This ensures against accidental truncation which could 
occur if you break out of BASICV via CTOL-P or BREAK. When this 
happens, all opened file units are left open. At PRIMOS command level, 
these file units can be closed with the CLOSE ALL command, discussed in 
Section 3. 
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SEGMENT DIRECTORIES 



A segment directory is actually a list of numbered entries which 
contain the addresses of data files. These numbered entries, 
referenced by nunber only (no ncimes) are called ' painters" because they 
point to, or reference, data files. The files to vAiich they point can 
be of any BASICV file-type. Accessing the data files listed under a 
segment directory requires an aclditional step in the DEFINE process. 

Opening a Segment Dire ctory Data File 

The process of opening a data file contained in a segment directory is 
best illustrated by example. Suppose we have in our current directory 
a segment directory SEGA which contains several pointers to data files. 
To access a certain ASCII data file referenced by one of these pointers 
(in this case. File 3), the segment directory must first be opened on a 
file unit as follov\s: 

EEFINE FILE #1='SEGA' , SEGDIR 

The segment directory SEGA is now opened on file unit 1. Next, we must 
choose the third entry, which contains the data file address: 

POSITION #1 TO 3 

The file pointer is now positioned to segment 3 and the address of the 
data file we want to open. To open this data file, another file unit 
must be assigned with a MIFINE FILE statement. A special convention is 
used to indicate that the data file being opened is part of the segment 
directory opened on the previous; unit: 

DEFINE FILE #2='(SD1)', ASC 

(SDl) refers to the file unit # 1 on which SEGh, the segment directory 
(SD) has been opened. The ASCII data file is now opened for reading or 

writing on unit 2. Both file units must remain open as long as the 

data file is being used. 

Del€;ting Data Files Fr om Segment Directory 

Data files in a segment directory can be deleted by using the REPLACE 
statement. The format of the statement is: 

REPLACE #unit SEG x BY SEG y 

The pointers x and y point to two files, (x) and (y) respectively, 
REPIACE deletes file (x) , and moves pointer y into pointer x, leaving 
pointer y empty. The original (x) is gone, and the original (y) has 
been renamed (x) . Refer to Figure 8-2 for a visual interpretation. 
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BEFORE: 



X 
Y 




AFTER: 



>1 

Y 




Figure 8-2. Deleting a SEGDIR Data File 
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MimS 



MID\S, or the Miltiple Index Data Access System, is a collection of 
interactive utilities and subroutines for the efficient management of 
index-sequential and direct- access data files. MID^^S provides the 
programmer with an efficient method of building, restructuring, 
deleting, searching and accessing keyed- index data files. Data entry 
lockout protection and multitple user access to files are also 
supported by MIDAS. BASIC/VM does not support the following MIDAS 
features: direct-access and secondary- index data. For more 
information on the features of MIDAS and the usage of the related 
utilities, consult the REFEREMTE GUIDE, MIDAS. 

Bri ef Descriptio n of MIDAS Files 

The first step in building a MIDAS file is the creation of a template, 
or file descriptor, for the MIDAS file. The FRIME-supplied program 
CREATK, is used to do this. It prompts the user for input describing 
the file to be created. The parameters supplied include the filename, 
access type (DA,SA), data subfile information including key type, key 
size for both primary and secondary indices. A MIDAS file can contain 
up to 20 indices, that is, 1 primary and 19 secondary indices. 

Maintenance of the file can be done by multiple users simultaneously. 
A lockout subroutine guards against simultaneous changes and deletions 
of data entries. Other operations are done by exclusive single user 
access. See the MIDAS reference manual for further information. 



MIEftS File Configuration 

Although MIDAS provides its own methods of accessing files, the 
statements provided by BASIC/A/M allow the user to access data in a 
MIDAS file and use it in a BASIC program. These statements can be 
thought of as operating on a MIDAS file configured as a rectangular 
matrix or two-dimensional array.. Each element of the matrix contains a 
unique data record pointer. Access to these data records is 
accomplished by specifying the correct 'coordinates' of a particular 
element or key in the matrix. See Figure 8-3. 
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INDEX SUBFILE (KEY NUMBER) (K) 



POSITION 
(KEY VALUE) 
(P> 



KEY (0,1) 



-\ 



KEY (1,1) 



■\ 



ARROWS ARE POINTERS 
TO DATA RECORDS 



KEY (0,2) 



■^ 



-\ 



KEY (2,1) 



-\ 



> 



■^ 



> 



KEY (0,3) 



■\ 



■\ 



> 



^^ 



I 



I 

4^ 



The MIDAS File modeled as a matrix consisting of 
index-subfile numbers (key numbers) on the X-axis, 
and key-positions (key values) on the Y-axis. 

Figure 8-3. Configuration of MIDAS file 
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The values of K and P (in the previous diagram) form the coordinates of 
data record pointers. 

Euring a file read, the 'READ' pointer moves around the array, allowing 
the user to obtain either the key or the data record pointed to by the 
key. Initially, the file 'READ' pointer is set to the first primary 
key or the upper left corner of the matrix. 



STATEMENTS 

The statements used to access MIEftS files in BASIC/VM are similar in 
function and format to those discussed earlier in this section. The 
parameters and arguments must be supplied in legal BASIC form. These 
statements are designed to perform a consistent and canplete set of 
movements around a MIDAS file structure, so that any sequence of 
statanents may be used without inconsistent or unpredictable results. 
Statements are listed below: 



Statement 



Function 



DEFINE 
ADD 

READ [KEY] 



Opens existing MIDAS file on specified unit. 

Adds record to end of MIDAS file. Does not 
change current record location. 

Reads data from MIDAS file: optional 

arguments specify record location. KEY option 

returns value of key to which pointer is 
currently positioned. 



POSITION 



REWIND 



Moves read pointer to any record in file; 
locks on record until pointer is 

re-positioned. 

Rewinds pointer to top of indicated column in 
file (:3ee figure 8-3) or to beginning of file, 
(defaalt) . 



UPDATE 
REMOVE 



Adds data to current record. 

Deletes one or more keys from MIDAS file: if 
primary key, deletes associated data. 



CLOSE 



Closes MIDAS file on indicated unit. 
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TERMS AND COSIVENTIONS 

The following is a list of special terms and conventions used in 
defining the MIDAS access statements. 

Definitions 

{...} Select any one of the vertically stacked elements. 

[...] Enclosed items are optional. 

* Indicates repetition, or more times. 

+ Indicates repetition, 1 or more times. 

Terms Definitions 

#unit File unit on v*iich MIDAS file is opened. 

KEY 

PRIMKEY The primary key. 

SAME KEY Positions to or returns datum only if next key 

matches current one. 

SEQ Supplied in lieu of key: next sequential record is 

positioned and read. 

num-expr-x Represents numeric expressions. 

str-expr-x Represents string expressions. 

MIDAS FILE HANDLING 

The BASICAM statements available for MIDAS file access are described 
below. The examples supplied with the descriptions of each statement 
are taken from the MIDAS-BASIC demonstration program that immediately 
follows the presentation of statonents. 

Opening a MIDAS File 

The EEFINE FILE statement opens a MIDAS file on an indicated file unit. 
If the record size is specified, the internal buffers are dimensioned 
to this value. The record size should be equal to the length of the 
data record. This information is defined in the MIDAS file by the 
CREATK utility. 
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DEFINE FILE #unit = str-expr, MIDAS [,nLBn-expr-l] 

#unit = file unit number on which file is opened 

str-expr = MIQ^lS filename 
num-expr-1 = record size (in words) 



Example : 

DEFINE FILE #1= 'DIR', MimS, 64 
Positionin g the File Fbinter 

The position statement positions the read pointer to any record in the 
MIDAS file. The record positioned to is locked up on positioning and 
un- locked vhen the pointer is EOSITIONed to another record. Note that 
there are no specific lock and unlock statements in BASIC/VM. 

SEQ 
POSITION #unit, { KEY [num-expr] = str-expr } 

SAME KEY 

num-expr = secondary key number (index subfile number) 
str-expr = key value (primary or secondary) 

Example: 

POSITION #1, &ME KEY 

READ ing a MICftS File 

Data are retrieved from a MIDAS file via the READ statement. The KEY, 
SAME KEY or SEQ options are used to specify the location of the record 
to be read. The READ KEY statement gives the actual value of the 
current key to which the pointer is positioned. 

SEQ 
READ[KEY] #unit [,{KEY [num-expr] = str-expr}], str-var 

SAME KEY 

num-expr = index subfile number 

str-expr = key value 

str-var = variable into which data is read from record 
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Example : 

READ #1, SEQ 

If SEQ is used in place of a key, the next sequential record, in key 
order, is read. SAME KEY returns a datum only if the next key is the 
same as the current one. If the keys do not match, an error trap is 
taken. READ statements pre-position and lock to the location specified 
by the KEY, SAME KEY or SEQ (sequential ) options. The data is then 
read and returned in the specified string variable. In the optionless 
form of READ, (e.g., READ #1, X$) , no positioning occurs and only the 
current record is read. 



Writing t o a MIDAS File 

The ADD statement adds a record to the MIDAS data base. It does not 
change the current record location. 

PRIMKEY 
ADD #unit, str-expr-1, { KEY [0-expr] } = str-exp-2 keylist 
where keylist = [,KEY num-exp-1 = str-expr-3] * 

0-exp = expression evaluating to zero 

str-expr-1 = MIDAS filename 

str-expr-2 = actual primary key value 

str-expr-3 = value of secondary key 

num-expr-1 = secondary key number (index subfile 

number) 

keylist = list of secondary key numbers and values 

ADD #1, X$, KEY0 = 1$ (1) 

The UPDATE statement adds a string expression to the current record on 
the specified file unit. If keys are being stored in the record, the 
UPDATE statement should not be used for changing these keys. BASICV 
does not monitor internal record structure and can not determine 
changes in a key field. 

UPDATE jfunit, X$ 

X$ = string expression to be 

written to current record. 
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Removing Data 



The REMOVE statement deletes a given key from the HWAS data base. If 
the key is a primary key (where nLim-expr=0) then the data associated 
with the primary key also is deleted. The language permits both 
multiple and single key removal in a single statanent. 

REMOVE #unit [, KEY [num-expr] = str-expr ] + 

Repos itioning th e File Pointer 

The REWIND statement is used to reposition the file pointer from the 
current index subfile to a specified point. This can be thought of as 
positioning the pointer to the top of an indicated colunn. If the key 
specification is omitted, the default KEY is assuned. This positions 
the pointer to the ipper left corner of the matrix, (equivalent to 
REWIND #unit, KEY 0.) 

REWIND #unit [, KEY num-expr] 
Example: 

REWIND #1, KEY3 (Set pointer to top of index subfile [KEY] 3) 
Closing a MIDAS File 

A MIDAS file is closed in the same manner as the data files previously 
discussed. The format is: 

CLOSE #unit 

SAMPLE PROGRAM 

The following program, MIDASDEMO, illustrates the use of the BASIC AM 
MIDAS access statements to retrieve record information from a MIEAS 
file. This program is included on the Master Disk shipped at Rev. 16 
and is available for general use. A description of the functions 
defined in the program follows: 



1 
2 
3 
4 
5 
5 
7 
8 
9 
10 ! 



** A VERY SIMPLE "MIDAS; QUERY LANGUAGE' ** 
MIDAS Demonstration Program 



This program demonstrates the use of MIDAS in a simple 
application. Central ideas to note are the use of multiple 
keys, storage of key fields as data, and the use of BASICV's 
string functions to automatically control string lengths, 
to perform space-padding, and facilitate string comparisons. 



11 ! The functions available via this program are: 

12 ! FIND [ALL] field-nanie field-value 

13 ! Finds one or all of the records with a the given value 
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in the field specified by field-name. Field names 

are requested from the user at the start of the program. 
ADD 

Allows the user to add a record to the data base. 

The user is prompted with the field names before 

being required to type in the record. 
LIST 

Lists out all records in the file. 



14 

15 

16 

17 

18 

19 

20 

21 

22 

23 

100 ON ERROR GOTO 680 ! first set a single error handler 

110 DIM I$(10) ! the input array 

115 ! 

116 ! First define all needed functions 

117 ! 

120 DEF FNP$(X$,N) ! pads X$ with spaces on right such that total 

length is N 
130 y$=x$ 

140 Y$=Y$+' ' UNTIL LEN(Y$)=N 
150 FNP$=Y$ 

160 FNEND 

161 ! 

162 ! 

170 DEF FNK(F$) ! returns a key (index subfile) number given a field 

name 
180 FOR I = 1 TO 10 
190 FNK = I-l 
200 IF K$(I)=F$ THEN GOTO 220 
210 NEXT I 

220 FNEND 

221 ! 

222 ! 

230 DEF FNI ! input function - gets space-separated strings from TTY 

and 

231 ! stores the sequence in 1$ (1) . ..1$ (n) 
240 INPUTLINE •.•,X$ ! prompt with a '.' 

250 X$=X$+' ' 

260 MAT I$^ULL 

270 FOR 1=1 STEP 1 UNTIL CVT$$ (X$,2) = " ! CVT$$ insures no blanks 

280 I$(I) = LEFT (X$, INDEX (X$,' •)-l) 

290 X$ = RIGHT (X$, INDEX {X$,' ')+l) 

300 NEXT I 

310 FNEND 

311 ! 

312 ! 

320 DEFINE FILE #1='DIR ', MIDAS, 64 

330 MATINPUr 'Fields: ',K$(*) ! field names, in order from KEY 

331 ! 

332 ! ** main loop ** 

333 ! 

340 D=FNI ! input ccmmand string 

345 ! 

346 ! FIND ALL 
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347 ! 

350 IF I$(1)='FIND' AND I$(2)=='ALL' THEN DO 

360 POSITION #1, KEY FNK(I$(3))=I$(4) 

370 READ #1, X$ 

380 PRINT CVr$$(X$,16) ! impress strings of blanks to one blank 

390 POSITION #1, SAME KEY ! find all records with this key value 

400 GOTO 370 

410 DOEND 

411 ! 

412 ! FIND 

413 ! 

420 IF I$(1)='FIND' THEN DO 

430 READ #1, KEY FNK(I${2))==I$(3) , X$ 

440 PRINT CVT$$ (X$, 16) 

450 GOTO 340 

460 DOEND 

461 ! 

462 ! ADD 
453 ! 

470 IF I$(1)='AIX>' THEN DO 

480 PRINT K$(I): FOR I = 1 TO 4 

490 PRINT ' '; 

500 D = FNI 

510 I$(1)=FNP$(I$(1),32) ! write data must be padded to correct 

length 
520 I$(2)=FNP$(I$(2),32) 
530 I$(3)=FNP$(I${3),32) 
540 I$(4)=FNP$(I$(4),32) 
550 Z$=I$(1)+I${2)+I$(3)+I$(4) 

560 ADD ltl,Z$,KEY0=I$ (1) ,KEY1=I$ (2) ,KEY2=I$ (3) ,KEY3=I$ (4) 
570 GOTO 340 

580 DOEND 

581 ! 

582 ! LIST 

583 ! 

590 IF I$(1)='LIST' THEN DO 

600 REi/\?IND #1 ! default is KEY 

610 READ #1, X$ 

620 FRINT CVT$$(X$,16) 

630 POSITION #1, SEQ 

640 GOTO 610 

650 DOEND 

651 ! 
552 ! 

660 PRINT '?• ! command error 

570 GOTO 340 

671 ! 

680! a single error handler !!!! 

681 ! 

690 IF ERR=56 AND ERL=390 THEN GOTO 340 

695 IF ERR=56 AND ERL=630 THEN GOTO 340 

700 PRINT ERR$(ERR): 'AT LINE':ERL ! fall through to system error 

720 END 
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Settir^ U p A MIDAS File 

The MIDASDEMO program operates on a MIDAS file vhose template is set up 
by the CREATK utility. A command file, listed below, invokes the 
CREATK utility and prompts the user for the template information. The 
tonplate is the skeleton for the file. It defines the keys on v>*iich 
data will be searched. 

After the template has been set up, the program can be run and the 
record information can be added to the file. 

OK, * FIRST MAKE AN EMPTY MIDAS FILE 

OK, CO C CREATK 

OK, CREATK 

GO 

MINIMUM OPTIONS? YES 

FILE NAME? DTO 
NEW FILE? Y^ 
DIRECT ACCESS? NO 

DATA SUBFILE QUESTIONS 

KEY TYPE: A 

KEY SIZE = : W 16 

DATA SIZE = : 48 

SECONDARY INDEX 

INDEX NO.? 1^ 

DUPLICATE KEYS PERMITTED? YE£ 

KEY TYPE: A 

KEY SIZE = : W 16 

USER DATA SIZE = : (CR) 



INDEX NO.? 2 

DUPLICATE KEYS PERMITTED? YES 

KEY TYPE: A 

KEY SIZE = : W 16 

USER EATA SIZE = : (CR) 



INDEX NO.? 3_ 

DUPLICATE KEYS PERMITTED? YES 

KEY TYPE: A 

KEY SIZE = : W 16 

USER DATA SIZE = : (CR) 



- 33 March 1979 



SECTION 8 PDR3058 



INESXNO.? (CR) 



OK, CO TTY 
OK, 



Descrip tion of MIDAS DeitiQ Program 

The MIDAS Demonstration program sets up a series of functions to make 
record access more flexible. Most of the MIDAS access statements 
dejscribed earlier are included in this program. 

The user-defined functions in this program are: 

FNP$(X$,N) - pads a given string, X$, with spaces to make it equal 
to length N. Uses system function LEW (Y$) which 
returns the ntmber of characters of string Y$. 

FNK(F$) - returns a key (index subfile) nunber given a field 
name. 

FNI - the input function; accepts string input from the 

terminal (TTY) and stores it in an array. Uses the 
system functions: CVr$$ vvrtiich reformats a given 
string according to the indicated mask (listed in 
table 10-3); INI:EX(X$,Y$)- computes the starting 
position of Y$ in X$. (In this case, firx3s first blank 
space in X$.) LEFT(X$,Y)- returns the left-most Y 
characters of string X$. (In this case, returns first 
characters immediately to the left of the first 
blank.) RIGHT (X$,Y) -returns right-most Y characters 
of string X$. In this case, those beginning after the 
first blank found in X$. 



After the functions that accept and organize input for the data file 
have been defined, the program opens the MIDAS file called 'DIR' on 
file unit #1. A record size of 64 words is specified, meaning that no 
data in excess of 64 v\»rds will fit into one record. 

DEFINE FILE #1 = 'DIR ' ,MimS, 64 



The user is then prompted to input field names in order, as shown in 
the sample dialogue below. The function FNI forms an array of these 
input strings. The prompt character for user input is defined as a 
single dot. 
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The program then defines what will occur when the user inputs the 
words, FIND or FIND ALL. The FIND ALL function incorporates the BASICV 
statements POSITION and READ„ 

POSITION #1, KEY FNK(I$(3)) = I$(4) 

The POSITION statement tells the read pointer to find the record 
referenced by the key(index subfile number), in this case FNK(I$(3)), 
whose value is given by the expression 1$ (4) . 

After the record is read and printed out, the pointer is told to 
position to the next record referenced by the previously specified key. 
This accomodates the use of duplicate keys (i.e., having more than one 
record or entry referenced by a single key). 

POSITION #1, SAME KEY 

Once a record is positioned to, the data in it can be READ into a 
specified string variable. The READ statement places all the data in 
the current record into strir-»g X$x. 

READ #1, X$ 

In this case, the specified key is given by FNK{I$(3) )=I$ (4) , and the 
record associated with this key will be read. The function then prints 
out the record and loops until all records corresponding to the given 
key are read and returned. 

The FIND function is similar to FIND ALL but only retrieves one 
specific record, the first one it encounters fitting the description 
given by the key. 

POSITION is not necessary when READing a MIDAS file. The read pointer 
will automatically position to the proper record v^en a key value is 
supplied with a READ statanent. 

READ #1, KEY FNK(I$(2))= 1$ (3) ,X$ 

Here, the key number and value are supplied and the record is 
.positioned to and read. The function then prints out the data in X$ 
and returns the user to the input function (FNI) at line 340. 

If the user types ADD at line 340, the program jumps to line 470 which 
begins an 'ADD' sequence. Data can then be added to the MIDAS data 
base with the ADD statement. First, the item must be padded to the 
correct length, which is accanplished by FNP$. This key information is 
then added to 'DIR' with the ADD statement. 
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ADD #1, Z$, KEY 0= I$(l), KEY1=I${2),KEY2=I$(3),KEY3=I$(4) 

(The subset containing 'KEYl' throLgh'lS (4) ' is a KEYLIST.) 

The LIST function makes use of the MIDAS access statements REWIND, READ 

and POSITION to generate a listing of all the records in the MIDAS 

file. The pointer is first wound to the beginning or (upper left 
corner of the matrix) of the file: 

REWIND #1 

No key is specified, therefore, KEY is assumed. The program reads 
the first record pointed to and prints it out. The next record is then 
positioned to with the statement: 

P0SITI0N#1, SEQ 

The SEQ paraneter tells the pointer to position to the next sequential 
record in the file. It may have the same key value as the record just 
read. This happens when duplicate keys are being used. This 

sequential 'posit ion- read' routine is done until the end of the file is 
reached . 

The raxtainder of the program handles errors, using the BASICAM error 
functions, ERR$ and ERR. See Section 15 for details. 

The following is an example of an actual interactive terminal session 
during vy^iich the DEMO program v/as run. 
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NEW OR OLD: OLD DEMO 
>RUN 



DEMO 



FRI, SEP 01 1978 



17:46:24 



Fields: NUM, NAME, CITY, STATE 

.ADD 

NUM NAME CITY STATE 

. ADD 

NUM NAME CITY STATE 

.ADD 

NUM NAME CITY STATE 

.ACQ 

NUM NAME CITY STATE 

.LIST 

1 JONES BOSTON MASS 

2 JAMES NEWTON MASS 

3 SMITH NYC NY 

4 AMES ORANGE NJ 
.FIND NAME JAMES 
2 JAMES NEWTON MASS 
.FIND ALL STATE MASS 

1 JONES BOSTON MASS 

2 JAMES NEWTON MASS 
.FIND ALL NAME J 

'J') 

2 JAMES NEWTON MASS 
1 JONES BOSTON MASS 
.FIND ALL STATE N 
4 AMES GRANGE NJ 

3 SMITH NYC NY 
.controlC. 
END OF DATA AT LINE 
>QUIT 



.1 JONES 


BOSTON 


MASS 


.2 JAMES 


NEWTON 


MASS 


.3 SMITH 


NYC NY 




.4 AMES ( 


DRANGE NJ 



(partial key access - finds all names starting with 



240 



DEMO RUN 
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Running the MIEftSDEMO 

The MIDAS file template set up by CREATK contains no data; they are 
entered by the user when tbie DEMO program is run. The first data 
requested by the program are the field names, vi^ich correspond to the 
primary and secondary keys. Data items are entered in response to the 
'.' character, which was established by the EEMO program as the input 
prompt. 

In the example session on the previous page, the 'ADD' function is used 
to add four separate records to the data base. The entries NUM, 
I^y^E, CITY and STATE correspond to the primary key (KEY 0), and 
secondary ke^ra, KEY 1-3, respectively. The various progranv-defined 
functions discussed earlier are then utilized. 

The Control-C break-out at the end of the program is possible only 
during input mode, or vhen the progran is waiting for input from the 
terminal. 

A complete summary of all the B?iSIC/VM MID?^S access statements can be 
found in reference Section 15 ir, the rear of this manual. 
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INTRODUCTICW 

Arrays and matrices are one or two-dimensional tables of contiguDus 
numeric or string values. A matrix consists of those elonents in an 
array with non-zero subscripts. Each array or matrix elonent is 
represented by a subscripted value (integral only). In a 

two-dimensional array element representation, the first subscript 
represents rows, the second, coluenns. Ihus, in array A, below, element 
(2,2) is in row 2, column 2. This is the last element in the array. 
Any non-integral subscript value entered is truncated to an integer 
before being used to locate the specified element. 

The DIM statement is used to dimension an array or matrix by setting a 
limit on the number of elements it contains. For example, the 
statement DIM A (2, 2) sets up a two-dimensional array with the following 
elements: 

(0,0) (0,1) (0,2) 

(1,0) (1,1) (1,2) (1,1) (1,2) 

(2,0) (2,1) (2,2) (2,1) (2,2) 

ARRAY A MATRIX A 

(all subscripts non-zero) 

Matrix A consists of those elements of array A having non-zero 
subscripts. The dimensions of matrix A are 2 by 2, i.e., tvfo rows by 
two columns. The actual dimensions of array A are 3 by 3: three rov« 
by three columns. 



ARRAYS 

Numeric Arrays 

A numeric array name is a simple numeric variable. An array name, 
followed by one or two parenthesized values, indicates an element in 
the array. For example, A(5) and B9(6) are elements in one-dimensional 
arrays. The values of all elements in a numeric array are initialized 
to at the beginning of the program in v\hich they are defined. 
Numeric array elements are assigned values like any other numeric 
variable, e.g., B9(6)=2. 
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String Arrays 

A string array is named by a simple string variable. String array 
elements are represented by an array name followed by one or two values 
enclosed in parentheses. For example, the following " are elements in 
string arrays: 

A$(5) (one-d;imensional array element) 

B$ (1+1,3) (two-d;:mensional array element) 

All elements of a string array are variable length character strings. 
Each element of a string array is initialized to null by the compiler 
at the beginning of program execution. String array elements are 
assigned values like all string variables, e.g., A$ (2)='steve' . 

Declaring an Array 

Array dimensions are established either by the DIM statement, by a MAT 
statement (such as l^T PRIN]') which references the array, or by the 
default value of (10) or (10,10}. The value of any subscript must be 
within the range of the defined array dimensions. 

The first element in any array is represented as (0) for a 
one-dimensional array or (0,0) for a two-dimensional array. However, 
these elements are not printed if MAT PRINT is used to output the 
array; only the matrix portion of the array will be output. 

Example; 

DIM A (5) 

defines a one-dimensional array of six elements: A(0) through A(5). 
DIM statements may appear an^Avhere in the program. Before execution 
begins, BASIC AM sets up the arrays internally using the following 
rules: 



1. If an array element is referenced in a program, such as A(l), or 
A (2, 3) but the array A has not been defined in a DIM statement, 
it is implicitly dimensioned to (10) or (10,10). 

2. If an array is defined irore than once by DIM, the first dimension 
sets its size. 

The following statemait defines a 10 by 10 array where element (1,1) 
has a value of 2. All other elements are 0. Its dimensions are 10 by 
10 (default) because it has not been previously dimensioned by DIM. 
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A(l,l) = 2 

Below are examples of one-dimensional and twD-dimensional numeric 
arrays defined by DIM. 

Qne-dimensional : 

10 DIM A (8) 

20 FOR N = TO 8 

30 A(N) = N 

40 PRINT A (N) 

50 NEXT N 

> RUN 



1 

2 

3 

4 

5 

6 

7 

8 
> 

Two-dimensional: (note that line 80 outputs matrix M, not array M) 



10 DIM M 


(3,4) 


20 FOR I 


= TO 3 


30 FOR J 


= TO 4 


40 M(I,J) 


= 3*1 


50 NEXT J 




60 NEXT 


I 


70 PRINT 


•M' 


80 MAT PRINT M 


90 PRINT 


LIN (2); 


100 FOR F 


= TO 3 


110 FCR G 


= TO 4 


120 PRINT M (F,G) 


130 NEXT G 




140 NEXT F 




150 PRINT 


LIN (2); 


XTOMPILE 




>EXE)CUTE 





- J+1 



'M' 



•DONE ' 
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M 

3 2 10 

6 5 4 3 

9 8 7 6 



M 

1 



-1 

-2 

-3 

4 

3 

2 

1 



7 

6 

5 

4 

3 

10 

9 

8 

7 

6 



DONE 



String Array Example: 

10 DIM B${2,2) 

20 B$ (1,1)= 'MICHELLE' 

30 B$(1,2) = 'BBCKY' 

40 B$ (2,1)= 'KAREN' 

50 B$ (2,2) = 'ARLENE' 

55 MAT PRINT B$ 

60 END 

>RUNNH 

MICHELLE BECP:Y 

KAf^EN ARLE:NE 
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MATRICES 

Matrices are dimensioned by the DIM statement, as are arrays, or are 
automatically defined v^en referenced by a MAT (matrix) statement. 
Such a matrix is assigned default dimensions of (10) or (10,10). The 
dimensions of the matrix may be changed to larger or smaller than 
original, using the MAT statement followed by new subscript values for 
the parameters (dim-1, dim-2). See Table 9-1. 



MATRIX OPERATIONS 

Matrix operations are valid only for that part of an array defined as a 
matrix, i.e., that portion with non-zero subscripts. Matrix operations 
include initialization, redimensioning, addition, subtraction, 
multiplication, inversion and transposition. All matrix operations 
begin with the keyword MAT and are listed in Table 9-1. All of the 
indicated operations, except MAT=NULL, can be performed on numeric 
matrices. String matrices can only be initialized to NULL or 
redimensioned with the ( dim ) option of the MAT statement. 

Table of Matrix Operations 

The following table lists all available BASIC/VM matrix operations. 
The parameter dim , e.g., (dim-1 [, dim-2]) represents a numeric constant 
or expression defining the dimensions of a matrix; num-expr represents 
a numeric expression by v\*iich a matrix may be multiplied. 
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Table 9-1. Matrix Operations 



Mathematical ; 

All elements are initialized 
to zero. (Matrix may be 
redimensioned.) 

All elements are initializecJ 
to one. (Matrix may be 
red imensioned . 

All elanents are initializecJ 
to zero except the main 
diagonal (elements with equal 
subscripts) v*iich is all ones: 
identity matrix. (Matrix 
may be redimensioned.) 

All elements of strirg array are 
nulled. Matrix is optionally 
red imensioned . 

All elements of two matrices are 
added to or subtracted from each 
other. 

All elements of a matrix 

are multiplied by an expression. 

Two matrices are multiplied,. 

All elements are transposed. 

The square matrix is inverted. 

Input/Output ; 

Within the program. 



Statements Used 



MAT X = ZER [(dim-1 [,dinr-2])] 



MAT X = CON [dim-1 [,dim-2])] 



MAT X = IDN [(dim-1 [,dim-2])] 



MAT A$ = NULL [(dim-1 [,dim-2];i] 



MAT X = X + Y or 
MAT X = X - Y 



MAT A = (num-expr)*X 
MAT A = X*Y 
MAT X = TRN (Y ) 
MAT X = INV(Y) 



MAT READ, Cff^NGE 
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Between program and terminal. MAT INPUT, MAT PRINT 

Between program and external 

files or devices. MAT READ #, MAT WRITE # 
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Initializing Matrices 

Matrices are assigned initial values by being equated to one of four 
matrix constants in a MAT statement. The matrix constants are 
identified by the mnemonics ZER, CCN, IDN and NULL. The ^RJLL constant 
applies to string matrices only; the remaining constants are used only 
for numeric matrices. 

The constant ZER initializes each element of the specified matrix to 0. 
The following statements define a 5 by 7 matrix and initialize each 
element to 0, respectively: 

DIM A (5,7) 
MAT A = ZER 

The constant CON initializes each element of the specified matrix to 1. 
The following statements define; a 2 by 3 matrix and initialize each 
elanent to 1, respectively: 

DIM B(2,3) 
MAT B = CON 

The constant IDN initializes the matrix to the identity matrix. All 
elements except those on the main diagonal are 0. The diagonal 
elements are 1. For IDN to be valid, the matrix must be square. 

Example : 

DIM A (3, 3) 
MAT A = lEN 

results in: 

10 
10 
1 

The constant NULL has the Scjne effect on string arrays as ZER has on 
numeric arrays; it initializes each element of the matrix to a null ■ 
value. The matrix can then be redimensioned. 

Example : 

>DI M A$(5) 

>A$(I) ^ 'ABCD' FOR I = 1 TO 5 

>MAT PRINT A$: 



>ABCD ABCD ABCD ABCD ABCD 
> MAT A$ = NULL 
X^IAT PRINT A$: 
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Redimensioning Matrices 

The constants ZER, CON, NULL and IDN can also be used to change the 
dimensions of the matrix. By specifying subscripts after the constant, 
the matrix is redimensioned and the value of each element within the 
matrix is set according to the constant used. The following examples 
illustrate this concept using CON and ZER: 

Example 1 ; 

DIM A(4,5) 

MAT A = CCN(3,3) 

Changes the dimensions of A from (4,5) to (3,3) and sets the value of 
each element to 1: 

111 
111 
111 



Example 2 ; 

DIM X(3,3) 

MAT X = ZER (4,2) 

Changes the dimensions of X from (3,3) to (4,2) and sets the value of 
each element to 0: 











The dimensions of a matrix can also be changed by assigning to it 
matrix of other dimensions. 

Example: 

DIM A(6,6) iTotal of 36 elements in matrix 

DIM B(5,4) ITotal of 20 elements in matrix 

MAT A = B !A is a 5 by 4 matrix of 20 elements 
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Matrix Addition 

The elements of two numeric matrices may be added and the values 
assigned to the corresponding elements of a third matrix. The example 
below adds the elements of matrix B to those of matrix C and stores the 
results in matrix A (called the target matrix): 

MAT A = B + C 

The source matrices (B and C) must have the same dimensions. The 
target matrix (A) is converted to the same dimensions as B and C. 

Figure 9-1 diagrams the addition of two matrices to produce values in 
the corresponding elements of a third matrix. 

One-dimensional Matrices: 
MAT C = A + B 



24 


5 


19 


37 


7 


30 


34 


12 


22 



Two-d imens ional Matr ices : 

MAT C = A + B 

26 22 6 14 20 3 12 2 3 
20 18 26 19 4 7 1 14 19 
45 28 13 8 23 10 37 5 3 



Figure 9--1, Matrix Addition 
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Matrix Subtraction 

The values in the elements of two matrices may be subtracted to produce 
the values in corresponding elements of a third matrix as shown in the 
following expression: 

MAT A = B - C 

The elanents of matrix A are set to the difference of the corresponding 
elements of matrix B and matrix C. Source matrices B and C must have 
the same dimensions. The dimensions of A become the same as those of B 
and C. 

Matrix Mjltiplication 

A matrix can be multiplied by a numeric expression or by another 
matrix. There are certain restrictions however, as explained below. 

Scalar Mjltiplication : A matrix may be multiplied by a numeric scalar 
expression and the results stored in a second or target matrix. 

In the following example, each element of matrix Y is multiplied by 5 
and the resulting values are assigned to matrix A. The dimensions of 
matrix Y then become those of matrix A. 

MAT A = (5)*Y 

Multiplication of Two Matrices : To multiply two matrices, both must be 
two-dimensional and the number of columns of the first matrix must 
equal the number of rows of the second matrix. The result is a third 
matrix with the same number of rows as the first matrix, and the same 
number of columns as the second matrix. 

The example below multiplies matrix B and matrix C to produce matrix A 
with dimensions of 2 by 4. 

DIM B(2,3) 
DIM C(3,4) 
MAT A = B*C lA is a 2 by 4 matrix 

Each element in matrix A is the result of multiplying the elanents of 
matrix B times the elements of matrix C in the following way: 

1. Multiply each element in row 1 of B, by each element in 
column 1 of C. 
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2. Add the results to obtain the value of the elonent in matrix 
A, row 1, colimn 1. 

3. Continue the pattern by multiplying row 1 and column 2 to 
produce element A(:-,2); row 1 and column 3 to produce 
A(l,3); row 2 and column 1 to produce A(2,l); row 2 and 
column 2 to produce A (2,2); and row 2 and colunn 3 to 
produce A(2,3). 



Example : 



B C 

12 7 8 9 

3 4 10 11 12 

5 6 16 17 18 



A = B * C 

A(l,l) = (1*7) + (3*8) + (5*9) 

A (1,1) = 7 + 24 + 45 

The first element in matrix A = 76 

The current values of the target matrix may not be used as part of the 
multiplication expression: 

MAT A = A*B (illegal) 
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Inverting and Transposing Matrices 

Matrix inversion is accomplished by using the INV function. A matrix 
can be inverted only if it is square and its determinant is not zero. 
Multiplying a matrix by its inverse yields the identity matrix. The 
determinant of a matrix is determined by the EET function (a numeric 
system function - see Section 10) . More information on 'DET' and 
matrix operations can be found in the following reference, or in most 
Linear Algebra texts. 

Thomas, George B., Calculus and Analytic Geometry, 4th edition , 
Addison-Wesley, Reading, Mass., 1968 

Zuckerberg, Hyam L., Linear Algebra , 

Charles E. Merrill, Pub., Columbus, Ohio, 1972 



The following example demonstrates the use of the inverse and 
determinant functions: 

MAT READ A 

IF DET A = THEN PRINT 'CANT INVERT' ELSE roiNT 'CAN INVERT' 

IF DET A <> THEN MAT C= B*INV(A) 

LATA 1,2,3,1 

It is often necessary to transpose a matrix so that it may be 
multiplied by another matrix. (Remember that two matrices can be 
multiplied only if the number of columns of the first matrix equals the 
number of rows of the second matrix.) For example, if a company sells 
four products and has three customers buying varying amounts of each 
product, the quantities would be set up in a 3 by 4 matrix (A). The 
cost of each product would be set up in a 1 by 4 matrix (B) . To 
determine the amount owed by each customer, matrix A must be multiplied 
by matrix B. Since you cannot multiply (3,4) * (1,4), you must 
transpose B: 

C=A*TRN(B) or C=(3,4)* (4,1) 

Figure 9-2 illustrates this concept. 
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Matrix A 




Customer 1 


100 


100 60 





Customer 2 





300 


10 


Customer 3 


50 


100 100 


100 



nuts 



tolts nails screws 



Matrix B 

Cost/item .10 .05 .01 .02 

nuts lx)lts nails screws 



C = A * TRN(B) 
= (3x4)* (4x1) 
= (3x1) 



Matrix C 



Customer 1 
Owes 

15.60 



Customer 2 
Owes 

3.20 



Customer 3 
Owes 

13.00 



Figure 9-2. Matrix Inverse 
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Every two-dimensional matrix has a transpose. TTnis is determined by 
rolling the matrix on the main diagonal. If matrix A is: 

4 2 

3 1 

its transpose is: 

4 3 
2 1 

and can be assigned to another matrix with the statement: 

MAT B = TRN (A) 

Both matrices are two-dimensional. The dimensions of matrix B are set 
to the reverse of those of matrix A. For example, if MAT A is (2,3) , 
MAT B will become (3,2). It is not legal to assign the transpose of a 
matrix to itself, i.e., MAT A = TRN(A) is illegal . 

Transmitting Matrix Data Within A Program 

As with general I/O, data can be read via MAT READ from DATA statements 
within the program. The values are assigned to each element of the 
matrix specified in MAT READ. 

Ihe dimensions of the matrix are first defined in a DIM statement. 
Then data values are read from EATA statement (s) until each element of 
the matrix has a value. The following example reads fifteen numbers 
from consecutive DATA statements and assigns them to matrix A: 

DIM A(3,5) 

MAT A = ZER 

MAT READ A 

DATA 1,2,3,4,5,6,7,8,9 

DATA 10,11,12,13,14,15 

The result is: 

A(l,l) = 1 
A(2,l) = 2 



A(3,5) = 15 
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Data Conversion 



Data may also be changed from a string of ASCII characters to a 
one-dimensional array containing the decimal equivalents of the 
characters (including parity) . Conversely, a decimal array may be 
changed to its correspond irej string of ASCII characters. Refer to 
^pendix B for the ASCII character table. To do either, use the CHANGE 
statanent. 

The following program changes the ASCII characters in D$ to an array of 
their decimal equivalents: 

10 DIM A(6) 
20 D$ = 'CHANGE' 
30 CHANGE D$ TO A 
40 FCR I = 1 TO 6 
50 PRINT A (I) 
60 NEXT I 



When run, the program prints: 



195 
200 
193 
206 
199 
197 

If the array has not been previously dimensioned, the CHANGE statement 
automatically dimensions the array to the length of the string. The 
zeroth elanent of the array contains the length of the string. In the 
above example, A(0)=6, because 'CHANGE' is six characters in length. 

Ihe following program converts decimal values listed in a UkTA 
statement, into their correspording ASCII characters and prints them: 

10 FOR X = 1 TO 6 

20 READ A(X) 

30 NEXT X 

40 DATA 208, 210, 197, 211, 212, 207 

50 CHANGE A TO A$ 

60 PRINT A$ 

When run, the program prints: 

PRESTO 
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Changing the zeroth elannent of a numeric array will alter the length of 
the corresponding character string of ASCII letters accordingly. For 
example, if A$='ABCEE' is converted to its numeric array equivalent, 
the first array elanent, A(0), will be equal to 5 because the string is 
five characters long. If the value of A(0) is changed to 3, a CHANGE 
of A to A$ will result in a string only three characters in length, 
e.g., A$='ABC'. 

Transmitting Matrix Data Between a Program and the Terminal 

Data to be stored in a matrix may be entered from the terminal. The 
MAT INPUT statement is identical to the INPUT statement except that the 
values entered are stored in matrix format. 

The following program segment defines matrix B as having six elenents. 
The MAT INPUT statement will expect six values to be entered. Each 
value will then be assigned to an element in matrix B: 

DIM B(2,3) 
MAT INPUT B 
MAT PRINT B 

When run, the following occurs: (user input is underlined) 

!10 
!15 

!I 
!20 

!25 

"13 

10 15 7 

20 25 13 

The MAT PRINT statement prints the values of the entire matrix at the 
tenninal. 

The MAT INPUT mat (*) statement is a variant of the MAT INPUT 
statement. It accepts one line of input and automatically dimensions 
the matrix, named by mat , to the number of items input. 

Matrix I/O to Data Files 

Matrices can be written to and read from data files with the MAT READ 
#unit and MAT WRITE #unit statements. Only the file handling 
statements v^ich deal with matrix I/O are presented here. Other data 
file handling operations are dealt with in Section 8 and Appendix E. 
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WRITEing a Matrix to a File 

Matrices are written to a data file with the MAT WRITE statement. 
First, the matrix is defimxJ with a DIM statanent. Values are then 
assigned to each matrix element. The entire matrix is then written to 
the indicated data file with a single MAT WRITE statement. 

Example: 

> OEFINE FILE #1 = 'MAT' 

> DIM A (3) 

> A(1)=10 

> A(2)=20 

>A(3)=30 

> MAT WRIT E #1, A 

>TYPE MAT 

10 20 30 

Reading From a File To a Matr ix 

Values written to a file with MAT WRITE can be read back with any of 
the READ statements covered in Section 8. They will be returned as any 
other data values stored in a file. The contents of a record or 
records in a file can be read into a matrix or matrices with the MAT 
READ or MAT READ* statements. The indicated matrices must first be 
defined with a DIM statement. Values are then retrieved from the 
record or records of the indicated file until the matrix or matrices 
are filled. 

The following example illustrates the use of MAT READ and MAT WRITE. 
Notice that an error trap for an end of file is included for the 
default ASCII file. An END OF FILE message is generated v>*ien a MAT 
READ is attempted on an ASC file. Values from an ASC file can be read 
into a matrix by defining the matrix and reading record values into the 
indicated variable with a RiEAD statement. MAT print can then be used 
to obtain a list of the values read into the indicated variable. 

Example: 

5 ON END #1 GOTO 120 

10 DEFINE FILE #1 = 'MAT' 

20 DEFINE FILE #2 = 'MAT2', ASCSEP 

30 DEFINE FILE #3 = 'ASCDA' , A32Dk 

40 WRITE #1, 20,20,20 

50 WRITE #2, 20,20,20 

60 WRITE #3, 20,20,20 

70 REWIND #1,2,3 

80 DIM A (2) 

90 PRINT 'READ I^IAT' 

100 MAT READ #1, A 

110 MAT roiNT A 

120 MAT READ #2, A 

130 FRIWr 'READ MAT2 ' 
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140 PRINT 

150 MAT PRINT A 

160 MAT READ #3, A 

170 PRINT 'READ ASCDA' 

180 MAT PRINT A 

190 REWIND #1,2,3 

MRUNNH 

READ MAT 

READ MAT2 

20 20 

READ ASCDA 

20 20 

STOP AT LINE 190 

>T YPE MAT 

20 20 20 

> TYPE 1V1AT2 

20,20,20, 

XTYPE ASCDA 

20,20,20, 

MAT READ* Statement 

The MAT READ* statanent functions just like the READ* statement. The 
read pointer remains positioned at the current record after a MAT READ* 
is executed rather than pre-positioning to the next record. This 
allows the next MAT READ* statement to continue reading data from the 
current record. 

Example: 

10 DEFINE FILE #1 = 'MATF ' , ASCSEP 

20 WRITE#1, 10,10,10,10 

30 WRITE #1, 20,20,20,20 

40 WRITE #1,30,30,30,30 

50 REWIND #1 

55 DIM A (5) 

60 MAT READ * #1,A 

62 MAT miNT A 

65 MAT READ * #1, A 

70 MAT PRINT A 

75 REWIND #1 

80 READ #1,A 

85 MAT PRINT A 

90 READ #1,A 

95 MAT PRINT A 

100 REWIND #1 

105 MAT READ #1,A 

110 PRINT A 

115 PRINT 
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120 MAT PRINT A 

130 REWIND #1 

> MARGIN 20 

»UNNH 

10 

10 

10 

10 

20 

20 
20 
20 
30 
30 

20 
20 
20 
30 
30 

20 
20 
20 
30 
30 

20 

10 
10 
10 
10 
20 

STOP AT LINE 130 
MARGIN OFF 




10 10 102 

20 20 303 

20 20 303 

20 20 303 



10 10 10 10 

20 
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Notice the difference between MAT PRINT and PRINT. HRINT merely prints 
the value associated with a scalar variable. MAT PRINT outputs the 
matrix named by a particular variable, e.g., A. This distinguishes the 
variable A from matrix A, as shown in the example. Notice also that 
the MARGIN statement can be used to alter the length of lines printed 
at the terminal. Ihis is useful for printing matrices in list, or 
tablular form. 
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SECTION 10 
NUMERIC AND STRING FUNCTIONS 



INTRODUCTION 

Most arithmetic operations can be simplified by using pre-defined 
numeric functions to handle routine calculations such as conputing 
square roots. String data handling can also be facilitated by 
functions designed specifically for manipulating strings. BASIC/VM 
provides both numeric and string syston functions to perform operations 
like calculating sine and cosine, generating random nanbers, and 
converting a string to its corresponding numeric value. In addition to 
system provided functions, users can define their own functions to 
perform special routines within a program. The functions available in 
BASIC/VM are: 

1. Numeric systan functions 

2. String system functions 

3. Numeric and string user-defined functions: 

This section lists all the currently defined systan functions, (both 
nimeric and string) , and provides information on defining and 
implementing user-defined functions of both types. A detailed 
discussion of call-by-value and call-by-reference functions is also 
included. 



NUMERIC SYSTEM FUNCTIONS 

A numeric function is identified by a three or four letter name (such 
as TAN) followed by one or more pararieters enclosed in parentheses. If 
more than one parameter is required, they are separated by ccxranas. 
Numeric functions operate on nutieric items or expressions. The result 
of a function operation is a single numeric value. Therefore, the 
function can be used anywhere in an expression vAiere a numeric constant 
or variable can be used. 



The following table lists the numeric systan functions provided by 
BASIC/VM. In all of the descriptions, X represents any numeric 
expression, and Y and Z represent any integers. 
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Table 10-1 Numeric System Functions 

ABS(X) Computes the absolute value of X. 

ACS(X) Computes the principal arccosine of X. The result 
is in radians in the range of to PI. 
360 degrees = 2 PI radians. 

ASN(X) Computes the principal arcsine of X. The result 
is in radians in the range of -PI/2 to PI/2. 

ATN(X) Computes the principal arctangent of X radians. The 
result is in the range of -PI/2 to PI/2. 

COS(X) Computes the cosine of X. The argument is in 
radians. Tl:.e result is in the range -1 to +1. 

COSH(X) Computes the hyperbolic cosine of X 
(defined as (EXP(X)+EXP (-X) )/2) . 

DEG(X) Computes the ntmber of degrees in X radians, 
[ (180/PI*X)] . The result is in degrees. 

DET(X) Computes the determinant of matrix X. If DET(X) 

unequal to 0, matrix X has an inverse. 

ENT(X) Computes the greatest integer that is less than or 
equal to X. 

ERL Returns the statonent number of the line v^^ich 

caused an error. 

ERR Returns the error code number of the last error. 

EXP{X) Computes e raised to the X power. 

INT(X) Performs integer truncation. 

If X=>0, returns the greatest integer <=X. 
If X<0, returns the least integer >-X. 

LIN#(X) For ASC LN files, returns the statonent number 

stripped frcm the last input on unit X. For BIN DA 
files, returns the current record position of the 
file on unit X. 

LOG(X) Computes the natural logarithm (base e) of X. 

NUM Returns the actual number of entries to MAT INPUT 

M(*) and MAT INPUT M$ (*) statements. Matrix M is 
one-dimensional . 

PI Computes the value of PI (3.14159). 
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RAD(X) 
RND(X) 



SGN(X) 



SIN(X) 

SINH(X) 

Sffl(X) 
TAN(X) 

TANH(X) 



Canputes the number of radians in X degrees. 

If X>0, uses X to initialize the random number 
generator and returns X as the function value. 
If X<0, uses X to initialize the randan number 
generator, and returns a value in the range zero 
to one. If X=0, returns a random number in the 
range zero <=result < 1. 

Computes a value based on the sign of X as follows: 
X<0 SGN(X)=-1 
X=0 SGN(X)=0 
X>0 SGN(X)=1 

Computes the sine of X. The argument is in 
radians. The result is in the range -1 to +1. 

Computes the hyperbolic sine of X defined as 
(EXP(X)-EXP(-X))/2. 

Computes the positive square root of X. 

Canputes the tangent of X. The argument is in 
radians. 

Computes the hyperbolic tangent of X defined as 
(EXP (X)-£XP (-X)/EXP (X)-ffiXP (-X) ) . 
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Using Some System Functions 

INT: The INT function can be Lised to round numbers: 

INT (2.9 + .5) = INT (3.4) = 3.0 

The INT function can also be used to round any numeric value to a 
specific number of decimal places. 

INT (10 * XI + .5) /10 
rounds XI to 1 decimal place. 

INT (100 * XI + .5) A00 

rounds XI to 2 decimal places. 

RND: The RND function generates random numbers. 

The following program yields tv^enty randcm integers of three digits or 
less: 

10 REM PROGRAM TO PRINT Ri^iNDOM NUMBERS OF 3 DIGITS CR LESS> 

20 FOR 1=1 TO 20 

30 L=RND (0 ) 

35 L1=INT(L*1000) 

40 PRINT LI 

50 NEXT I 



The RND function can also be used to define random ntmbers within a 
specific range. This is demonstrated by the following guessing game 
program. 

10 PRINT 'WHAT NUMBER AM I THINKING OF ' 

20 FOR C=0 TO 3 

30 N=INT (50 *RND(0) + 1) 

40 INPUT X 

50 IF X<N GOTO 90 

60 IF X>N GOTO 110 

70 PRINT 'RIGHT ANOTHER' 

80 GOTO 150 

90 PRINT 'TOO LOW' 

100 GOTO 120 

110 PRINT 'TOO HIGH' 

120 NEXT C 

130 PRINT 'TIME IS UP, ANOTHER' 

140 INPUT A$ 

150 IF A$ = 'Y' GOTO 120 

Tlie following program uses many of the system functions previously 
described. 
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100 ! EXAMPLE TO SHOW USE OF SYSTEM FUNCTIONS 

110 ! 

120 ! DAH 12/13/77 

130 ! 

140 LET V = RAD(l) ! 0.01745329251994 

150 1 1 DEGREE IN RADIANS 

160 W= RAD (30) 10.5235987755983 

170 X = RAD (45) ! 0.7853981633974 

180 Y =RAD(60) ! 1.047197551197 

190 Z = RAD(90) ! 1.570796326795 

200 1 W,X,Y,Z EQUIVALENTS 30,45,60,90 DEGREES RESPECTIVELY 

210 ! 

220 ! TRIGONOviETRIC FUNCTIOvJS CALCULATIONS 

230 SI = SIN (V) 

240 S2 = SIN (W) 

250 S3 = SIN (X) 

260 S4 = SIN (Y) 

270 S5 = SIN (Z) 

280 CI = COS (V) 

290 C2 = COS (W) 

300 C3 = COS (X) 

310 C4 = COS (Y) 

320 C 5 = COS (Z) 

330 Tl = TAN (V) 

340 T2 = TAN (W) 

350 T3 = TAN (X) 

360 T4 = TAN (Y) 

370 T5 = TAN (Z) 

380 Al = ATN (Tl) 

390 A2 = ATN (T2) 

400 A3 = ATN (T3) 

410 A4 = ATO (T4) 

420 A5 = ATN (T5) 

430 PRINT 'DEGREES', 'SIN', 'COS', 'TAN', 'ARCTAN' 

440 PRINT 

450 PRINT 1, SI, CI, Tl, Al 

450 PRINT 30, S2, C2, T2, \2 

470 PRINT 45, S3, C3, T3, A3 

480 PRINT 60, S4, C4, T4, A4 

490 PRINT 90, S5, C5, T5, A5 

500 ! 

510 1 ARITHMETIC FUNCTIONS (LOG ETC) 

520 ! 

530 X =7.50 

540 L = LOG(X) 

550 E = EXP(X) 

560 Q = SO^ (X) 

570 A = ABS(X) 

580 I = INT (X) 

590 P = SGN(X) 

600 ERINT 

610 PRINT 

620 PRINT 'NUMBER =' , X 
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630 PRINT 
640 PRINT 
650 PRINT 
650 PRINT 
670 PRINT 
680 PRINT 
690 PRINT A, 
700 PRINT 

PRINT 

! RANDOM 



'LOG(X)=', 
'EXP (X) = ', 



710 
720 
730 
740 
750 
760 
770 
780 



•S(^ARE ROOT', Q 
•ABS(X)', •INT(X)', 'SIGN(X)' 
I, P 

NUMBER FUNCTIONS 



'RANDOM NUMBER FUNCTIONS ' 



PRINT 

PRINT 

PRINT 'RND(0)', 'RND(N)', 'RND(-W) 

PRINT 

Zl = RND(0) 
790 Z2 = RND(l) 
800 Z3 = RND(-l) 
810 PRINT Zl, Z2, Z3 
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Sample Output: 



>DEGREES 


SIN 


COS 


TAN 


ARCTAN 


1 


.01745240643728 


.9998476951563 


.01745506492822 


.01745329251994 


30 


.5 


.8660254037844 


.5773502691896 


.5260879918124 


45 


.7071067811865 


.7071067811866 


.999999999999 


.7878873796115 


60 


,8660254037844 


.5 


1.732050807569 


1.047197551197 


90 


1 


4.464471677451E-14 


2.239906695009E+13 


1.570796326795 


NUMBER= 


7.5 








LOG (X) 


2.014903620542 








EXP 


1808.042414456 








SQUARE ROOT 


2.738612787526 








ABS (X) 


INT(X) 


SIGN(X) 






7.5 


7 


1 






RANDOM NUMBER 


FUNCTIONS 








R^D (0) 


RND (N) 


RND (H^) 






.2112731933594 


1 


.2112731933594 
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STRING SYSTEM FUNCTIONS 

String functions are used to obtain information about, or to operate 
on, a string or portions of a string. For example, the function 
SUB(X$,Y, [Z]) , returns a substring, beginning with character Y, of a 
larger string, X$. String functions, e.g., STR$ (X) , can also convert a 
numeric item to its corresponding string representation; or they 
convert the string representation of a number to the numeric value it 
represents, e.g. VAL (X$). A string function is identified by a three 
to five letter name followed by one or more parameters enclosed in 
parentheses. Parameters can be numeric or string items depending on 
the type of operation the function performs. 

Table 10-2 al0iabetically lists the string functions provided by 
BASIC/VM. In all descriptions, X represents any numeric expression, Y 
and Z represent any integers, and X$ represents any string expression. 
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Table 10-2 String System Functions 



CHAR(X) 
CODE (X$) 

CVT$$(X$,Y) 

D^TE$ 
INDEX(X$,Y$, [Z]) 

LEFT(X$,Y) 
TIMES 

MID(X$,Y,Z) 

LEN{X$) 

RIGHT {X$,Y) 

STR$(X) 

SUB{X$,Y, [Z]) 



VAL(X$, [Y]) 



Returns the character v*iose ASCII code is X. 
X is in the range 128-255. 

Computes the decimal ASCII code of the first 
character of X$. Codes are listed in ^pendix B. 
Note: the code of a null string is -1. 

Reformats X$ according to the mask Y. (Masks 
are listed in Table 10-3). 

Returns the date as YYMMDD. 

Computes the starting position of Y$ in X$, 
optionally beginning at character Z. 

Returns leftmost Y characters of X$. 

Returns the time as HI-MMSSFFF. 
(FFF is milliseconds) 

Returns Z characters of X$ starting at 
position Y. 

Returns the length (number of characters) 
of string X$. 

Returns rightmost characters of X$ fc>eg inning with 
character number Y. 

Returns the string representation of the 
number X. 

Returns a substring composed of characters 
in positions Y through Z of string X$. 
If Z is not specified, the result is a 
one character substring consisting of 
character Y of string X$. 

Converts a string, X$, to the numeric value it 
represents. Y will have the conversion status: 
0=successf ul , l=unsuccessf ul . If unsuccessful, 
run-time error occurs. 
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Table 10-3. Masks For CVr$$ 

MASK FUNCT ION 

1 force parity bit off 

2 discard all spaces 

4 discard .NUL. ,.NL. ,.FF. ,.CR. ,.ESC. 

8 discard leading spaces 

16 reduce multiple spaces to one space 

32 convert lower case to upper 

64 convert [ to ( and ] to ) 

128 discard trailing spaces 

(Masks can be con±)inecl additively) 
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Usir^ String Functions 

The following example utilizes several string system functions. 
Appendix A contains a sample program that uses string functions more 
extensively to format a block of text. 

Example ; 

10 REM USING SOME STRING FUNCTIONS 

20 PRINT 

30 X$= 'SOMEBODY KILLED HER HIBBAND' 

40 PRINT 'VALUE OF FOLLOWING SIRING: ' 

50 PRINT 

60 PRINT X$ 

70 PRINT 

80 LI =LEN(X$) 

90 PRINT 'LENGTH OF STRING=': LI 

110 PRINT 

115 B$ = SUB (X$, 21, 28) 

120 PRINT 'SUBSTRING IN POSITIONS 21 -28 IS: 'rSS 

150 END 

When run, the program results in the following output: 

VALUE OF FOLLOWING STRING: 

SOMEBODY KILLED HER HUSBAND 

LENGTH CF SIRING = 27 

SUBSTRING IN POSITIONS 21 -28 IS: HUSBAND 
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USER DEFINED FUNCTIONS 

In some programs it is necessary to execute the same sequence of 
statements or mathematical formulas in several different places. 
BASIC/VM allows you to define your own functions and use them just like 
systan functions. 

Numeric User-Defined Function s 

The name of a user-defined numeric function consists of the letters FN 
followed by a letter or a letter and a digit as shown below: 

FNA or FNPlV 

A reference to a user-defired function consists of the name of the 
function followed by a parenthesized argument expression. A function 
must be defined by a DEF statement. This definition must occur prior 
to the place where the function is called or referenced in the program. 

Example: 

DEF FNA (X2) =3.14 * X2+2 

A user-defined function reference may be included as an operand in an 
expression such as: 

LET Al = 3. 14 /FNA (XI) 

The argument of a user-defined function may be an arithmetic 
expression. The expression is evaluated, and then the value of the 
expression is substituted for the argunent in the function definition. 



Example: 



LET Al = 3.14 * FNA (XI + COS (B) ) 



A user function may also be more than one line. After the last line of 
the function, use the FNEND statement to indicate the end of the 
function definition. 

Example: 

CEF FNA (I) 

IF 1=0 THEN FNA^l EISH FNA = 1*1+1 

FNEND 

When program execution begins, ::he function definition is ignored until 
the function is referenced. Each time it is referenced, program 
control returns to the lines which defined the function. 
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String User-Defined Functions 

As with numeric functions, you may define your own string functions. 

The name of the function consists of the letters FN followed by a 
letter (or a letter and a digit) and a dollar sign ($) as shown below: 

FNA$ or FNA7$ 

A user-defined function must be defined by a EEF statement. If it is 
more than one line long, the last line must be FNEND, indicating 
termination of the definition. When program execution begins, the 
function definition is ignored until the function is referenced. Each 
time it is referenced, program control returns to the lines v*hich 
defined the function. 



Example: 



10 REM A PR(DGRAM WITH SUB ROOT INES 

20 REM AND SIRING FUbCTIONS 

30 DEF FNA$ {X$, Y$) 

40 FNA$=X$ 

50 IF X$>Y$ THEN FNA$=Y$ 

60 FNEND 

70 



100 IF A=l THEN 1000 

m 

150 X$=FNA$(B$,C$)+D$ 
1000 PRINT 'A EQUALS C»JE ' 
2000 GOSUB 5000 



2500 B$=FNA$(X$,Y$)4B$ 
3000 GOTO 100 



5000 Z$=FNA$(X$,Y$)+C$ 
5010 PRINT 'LINE 5010' 



6000 RETURN 
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Program executions begins at line 70. Assuming A=l, control jumps from 
line 100 to line 1000. At line 2000, control transfers to line 5000. 
Because the function is referenced, control transfers to lines 30 
through 60 where the function is defined. Control then returns to line 
5010. 

User-defined string functions may also be used in conjunction with 
system functions, as in: 

DEF FNF$ (A,B,C) = LEFT (STR$ (A-tB-tC) ,5) 

Defining Functions 

A function in BASIC/VM is defined with a parameter, e.g., DEF FNA(x), 
where x is the parameter. The parameter must be an identifier for a 
variable or for an array. A parameter is sometimes refered to as a 
dummy variable. 

A function is called in the program by an expression consisting of the 
function name (e.g., FNA) followed by a parenthesized argument or set 
of arguments. 

Example : 

DEF FNA(x) X is a parameter of function FNA 

x^ duirmy variable set equal to 5 

FNEND denotes end of function 



y=10 external program variable ^ '■ 

Z=FNA(y) expression calling function FNA; y is argument, 

sharing value with dummy variable x. ' ,; 

Call-By-Reference vs. Call-B^ '^-Value 

Generally, there are two ways in wh'.ch an argument can reference or set 
parameters in the function it calls: by value or by reference. This 
relationship between arguments and parameters determines whether the 
function is termed call-by-refsrence or call-by-value. This, in turn, 
is dependent upon the language in v^iich the function is being used. In 
BASIC/VM, functions are call-by-reference. 

In call-by-reference functions, arguments set parameters by reference. 
When a parameter is set by reference, every subsequent reference to 
that parameter actually becanes a reference to the storage location 
(slot v^ere the value of the variable is stored in menory) , of the 
argument that set it v\rtien the f jnction was called. In other words, 
every assignment of a value to the parameter is in effect an assignment 
of the same value to the argument that set the parameter. (The 
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argument itself is essentially substituted for the parameter in the 
function.) 

In the case of call-by-value , however, the value of the argument is 
actually copied to the storage location of the parameter called by the 
argument. Assignment of a value to the parameter effectively results 
in the value being placed in the parameter's storage location. 

For example, the previous function call (above) will produce two 
different end results (for y) depending on vhether the parameter x is 
called by reference or called by value. 

Call Method End Result 

1. Call-by-reference y=5 

2. Call-by-value y=10 

In the first case, argument y is essentially substituted for parameter 
X. Every subsequent reference to parameter x actually becones a 
reference to the storage location of argument y. Each assignment of a 
value to X is in effect an assignment of the same value to y. Thus y 
is passed through the function and returns a new value (5) to y's 
storage location. The argument y now has a new value in the external 
program. 

Call-by-reference functions obviously change the value of an argument 
passed through than. This fact should be noted so that strange results 
emanating from a program containing user-defined functions do not 
unduly alarm the programmer. 

Jjn.the call-by-value case, the argument y passes only its value (10) to 
thi duirmy variable x. It does not itself pass through the function 
FtSK. At the end of the pass, y remains unchanged because the parameter 
X does not return a value to argument y's storage location. In this 
example, y itself remains external to the function and thus retains its 
original value of 10. It can be inferred that arguments cannot return 
values from a function pass in call-by-value systems. 

Forcing Call-by-Value 

It is possible to force an argument to set a parameter by value in a 
call-by-reference system, such as BASIC/VM. The parameter in the 
function definition is modified to create a temporary value inside the 
function V(*iich will be passed through with no affect on the calling 
argument's original value. 
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Example: 

Forced 
Call-by-Value Call-by-Reference 

A = FNA(x+0) A = FNA(x) 

1) X is loaded into the 1) call FNA 
accunulator 

2) is added to it 2) argument pointer references x 

3) the result is stored in a 3) the result is stored in A 
temporary storage location 

Tl 

4) call FNA 4) the argiments' storage location 

is updated. 

(direct correlation between 
argument and parameter x, 
no local value for x is 
created) 

5) the argument pointer 
references Tl and the 
function operates on va'.ue 
in Tl 

6) the value is then stored in A 

7) the arguments' storage 
location is not updated 
because the storage location 
for {x+0) is unchanged; 

the argiment pointer re;:erences 
Tl only and is local to 
the function. 

The following program is an ex;3mple of a call- by- reference function: 

100 DEF FNA (X) 

110 Y=X*X 

120 X=Y+1 

130 FNA = Y 

140 FNEND 

150 X=l 

160 Y=2 

170 Z=3 

180 PRINT 'X': 'Y': 'Z';: 'FNA(Z) ' , 'X' 

190 PRINT X: Y: Z: FNACJ) , X: Y: Z 

200 END 

In this program, the following occurs: 
REV. ;.0 - 16 



I V . »7 I 



PER 30 58 



NUMERIC AND STRING FUNCTIONS 



1. The function of X is defined in lines 100-140. Since X is a 
dunimy parameter, changing X in the function definition does not 
change the actual value of X. 

2. Line 110 changes the variable Y to equal X2 

3. Line 120 changes the argument v\*iich corresponds to the 
parameter X. 

4. Line 130 sets the value of the function to Y. 

5. Line 180 references the function by using the argument Z which 
is passed to parameter X. Therefore, when X changes, Z is also 
changing. 

The resulting output is: 



X Y Z FNA(Z) 
12 3 9 



X Y Z 
1 9 10 



Function Definitions and Program Control 

The following program danonstrates the transfer of program control via 
function definitions and GOSUB statements: 

10 REM A PROGRAM WITH SUBROUTINES 

20 REM AND FUNCTIOSIS 

30 DEF FNA (X) 

40 IF X=0 THEN FNA=-1 ELSE FNA = X*X+J 

60 FNEND 

70 



100 IF A=l THEN 1000 



150 X^NA(3) 



1000 PRINT 'A EQUALS CWE ' 



2000 GOSUB 5000 
2010 



10 
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2500 Y=€lik (G ) 
3000 GOTO 100 



5000 Z^NA(I) 
5010 



6000 RETURN 

Program executions begins at line 70. Assuming A=l, control jumps from 
line 100 to line 1000. At line 2000, control transfers to line 5000. 
Because the function is referenced, control transfers to lines 30 
through 60 where the function is defined. Control then returns to line 
5000 for the assignment and continues with 5010. After 6000, control 
returns to 2010. Functions may also be recursive (i.e., they may call 
themselves.) For example, 

100 DEF FNF(X) ! Factorial 

110 IF X<=1 THEN FNF = 1 EISE FNF = X*FNF{X-1) 

120 FNEND 



Avoiding Function - I/D Inter action 

When user-defined functions are included in a program, control 
statements should not be made frcxn inside a function definition out nor 
from outside in. This can causie system stack difficulties leading to 
m^nory overflow. Additionally, when dealing with functions., that 
perform I/O operations, (e.g., READs, WRITES, roiNTs, INPUTs) the 
programmer should avoid calling these functions within other. I/O 
statements. In other words, it is potentially confusing to the I/O 
handler to call a function to do a RE^D, for instance, while tb^ 
function is being printed, line resulting printout will reflect this 
strange interaction of function READs and I/O PRINTS. 

In the following example, the function FNI$ performs the I/O function 
READ in both programs. In the first program, WRONGEROG, the function 
is placed on the I/O list and is called to READ while it is being 
printed. The second program solves the problem of potentially 
ambiguous I/O by assigning the information returned by the function 
READ process to a temporary variable. Then this information will not 
be intermixed with the actual printout of the function. 

Example : 

WROMCKIOG 

10 ! THIS IS WRO^GPROG 

20 ! THIS PROGRAM MAY CONE'USE THE I/O HANDLER 

30 ! 
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55 ! THIS IS ONLY A PORTION OF A LARGER PROGRAM 

60 DEF FNI$(A) ! READS A STRING FRCM FILE UNIT A 

70 ! 

75 READLINE #A,X$ 

80 FNI$ = X$ 

90 ! 

100 ! 

110 FNEND 



180 ! READ FILE 'YYY' , PRINT ON TERMINAL 

200 A=l 

210 DEFINE FILE #A = 'YYY' 

220 FOR 1=1 UNTIL 1=2 

230 PRINT FNI$ (A) 

235 I NO TEMPORARY VARIABLE ASSIGNED TO FUNCTION READ 

240 NEXT I 



RIGHTPROG 

10 ! THIS IS RIGHTPROG 

20 ! THIS PROGRAM DOES NOT CONFUSE THE I/O HANDLER 

30 

55 

70 

75 READLINE #A,X$ 

80 FNI$ = X$ 

90 ! 

100 ! 

110 FNEND 



THIS IS ONLY A PORTION OF A LARGER PROGRAM 



180 'READ FILE 'YYY', PRINT ON TERMINAL 

200 A=l 

210 DEFINE FILE #A = 'YYY' 

220 FO^ I = 1 UNTIL 1=2 

230 T$ = FNI$ (A) ! ASSIGN VALUE RETURNED BY READ FUNCTION 

240 ! TO A TEMPORARY VARIABLE 

250 PRINT T$ 

260 NEXT I 
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INTRODUCTION 

The properties of numeric data as supported by BASIC/VM are described 
in this section. Refer to Section 12 for string data properties. 

BASIC A'M numeric data is double-precision and floating-point, having a 
level of accuracy to 13 places in the mantissa and two places in the 
exponent. Numeric items consist of constants, variables, arrays and 
functions. They are also known as operands because they are 
manipulated or operated on within a program. 

A numeric constant is a numeric itan whose value does not change (and 
cannot be changed) during program execution. A numeric variable is the 
representation of a value which may or may not change during program 
execution. Numeric arrays and matrices are one or two-dimensional 
arrangements of data in rows and columns and are detailed in Section 9. 
Numeric functions are discussed in Section 10. 

Numeric Constants 

A numeric constant may be an integer, a decimal, or an exponent. A 
decimal may have an optional sign (+ or -) , a decimal point or an 
exponent specifier. Exponents consist of the letter E (signifying base 
10), and an optional sign (+ or -) followed by one or two digits. 
Exponential representation in BASIC/VM is very flexible; for example, 
.001 can be written as lE-3, .01E-1, or 100E-5. 

Note 

If more than thirteen digits are generated during 
any computation, the result of that computation is 
automatically printed in E format. (If the 
exponent is negative, a minus sign is printed after 
the E: lE-04; if the exponent is positive, a plus 
sign is printed: lE+04.) 

If decimal points are omitted, BASIC AM assumes them to be located 
imnediately to the right of the last significant (i.e., rightmost) 
digit. If the signs of either the constant or the exponent are 
emitted, BASIC/VM assimes them to be positive. 
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The following are examples of acceptable numeric constants: 

12 

-6. 556 

2.5E-2 (.025) 

Numeric Scalar Variables 

A numeric scalar variable (alsD called simple numeric variable) is a 
single letter (A-Z) , or a single letter followed by a single digit 
(0-9). Each variable represents a single numeric value; there are 285 
possible numeric scalar variables. A numeric scalar variable is 
initialized automatically to at the start of the BASIC/VT^ program 
that defines it. Examples of acceptable numeric scalar variables are: 

A, Al, X. 

Numeric Subscripted Variables : Arrays and Matrices 

A numeric array or matrix is named by a simple numeric variable, e.g., 
A, A6. A simple variable followed by a parenthesized value or pair of 
values, is known as a numeric subscripted variable or an array ©lement*. 
A singly subscripted variable or array name represents an element in a 
one-dimensional array, e.g., A(5). A doubly subscripted variable 
indicates a two-dimensional array elanent e.g., A(3,5). In a 
two-dimensional array, the first subscripted value represents row 
location; the second value represents column. For example the array 
elanent in location A(3,5) is visualized as being in row 3, column 5, 
of array A. 

In BASIC/VM, a matrix is zhat part of an array v»^ose elanents have 
non-zero subscripts. For ex.ample, an array dimensioned as A (5) 
actually has 6 elements; A(0)-A(5). Matrix A has only 5 locations: 
A(l)-A(5). 

Matrices and arrays also are dimensioned with the DIM statement, e.g., 
DIM A (5). Matrices can be defined or redimensioned with the MAT 
statement. See Section 9 for details. 

Distinguishing Variable an d Ar ray Names 

A numeric variable and a numeric array may share the same name e.g., B, 
in a program. The use of parentheses distinguishes one from the other. 
For example: 

3=2 

defines and assigns a value to a numeric scalar variable, while 

DIM B(2) 
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defines a numeric array, B, with a dimension of 2 rows by 1 column 
(assumed) . 

It is possible to have an array and a simple scalar variable with the 
same name in a program, but it is not possible to have both a 
one-and-two dimensional array with the same name, i.e. A(l) and 
A{1,1). 

The following shows how numeric constants, variables, arrays, matrices 
and array or matrix elements are defined. 

Type Examples 

Constant 12 

12.5 
5E2 

Scalar Variable A=3 

A7=12 

Array or Matrix DIM A (6) 

DIM A (5, 5) 

Array or Matrix A (6) =5 

or A(3,5)=10 

Element 



NUMERIC EXPRESSIONS 

Numeric expressions are constructed from numeric operands including: 

numeric variables or array (matrix) elements 

numeric constants 

references to a numeric function 

and numeric operators, including: 

arithmetic operators 
relational operators 
logical operators 

Expressions can be evaluated by arithmetic or string operators to a 
single value vy^ich may be used elsewhere in the program; or, they can 
be evaluated logically or relationally to a value of true or false. 
Program control flow may be decided on the basis of this value, as in a 
conditional GOTO expression. 

OPERATORS 

A numeric operator may be one of three main types depending on the kind 
of operation it performs: arithmetic (unary or binary), relational, 
and logical. 
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Operators vAiich require one operand are called unary. They indicate 
the sign, positive (+) or negative (-1) , of a numeric iton. Operators 
which require twD operands are called binary. Table 11-1 lists all 
operators according to type. Operators are evaluated according to a 
set priority list. See Order o f Expression Evaluation , following. 
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Table 11-1. Nuneric Operators 



Operator 



Meaning 



Example 



Arithmetic 
Operators : 



Relational 
Operators: 



Log ical 
Operators: 







******* 












*UNARY* 












******* 








+ 




plus 






+1 






minus 

******** 

♦BINARY* 
******** 






-I 


+ 




addition 






I-KJ 


- 




subtraction 






I-J 


* 




multiplication 






I*J 


/ 




division 






I /J 


-^ (or 


**) 


exponentiation 






I "2 


MOD 




ranainder from division 


I MOD J 






(Modulus) 








MIN 




lesser value 






I MIN J 


MAX 




greater value 






I MAX J 


= 




equal 






I=J 


< 




less than 






I<J 


> 




greater than 






I>J 


<= or 


=< 


less than or equal 


to 


i<=a 


>= or 


=> 


greater than or 


equal to 


i>=j 


<> or 


X 


not equal 






KXJ 


AND 




logical "and" 






1=0 AND K$=L$ 


OR 




logical "or" 






i<r OR I=K 


NOT 




logical complani 


ant 




NOT (KI) 
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Arithm e tic Operators 

Arithmetic operators come in two flavors, unary and binary. Unary 
operators require only one ojperand. Therefore, if the operator is the 
minus sign (-), the value of the operand will be negative. If the 
operator is the plus sign (+) , the value of the operand will be 
positive. The operand can be a parenthetical expression. Examples: 

FRINT -(A+B) 
PRINT -A 
FRINT -ffi 



Relational Oper ators 

BASIC/VM has six relational o{)erators: 



Operator 


Meaning 




Examples 


< 


less than 




X<Y 


> 


greater than 




X1>Y1 


= 


equal 




i=ai 


S) 


less than or 


equal 


J2<=J3 




greater than 


or equal 


Z>=10 


X 


not equal 




D019 



The interactions of relational operators and operands are referred to 
as relational operations. 

L ogical Operators 

The three logical operators, ;vND, OR, NOT are used in forming logical 
expressions. Logical expressions can be composed of variables and/or 
relational operations connected by one or more logical operators. They 
are evaluated to true or false. Figure 11-1 illustrates the evaluation 
of logical expressions under different true-false conditions. An 
expression that is true has a value not equal to 0; if false, it has a 
value of 0. 

Relational operations are used v/ith logical operators to form logical 
expressions. The result of a logical expression evaluation (true or 
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false) can be used to determine the flow of control within a program. 
For example, the following simple program shows the use of relational 
operations and logical expressions to form conditions for control 
transfer. 

10 INPUT A,B 

20 IF A>B AND BO0 GOTO 80 

30 IF A<B GOTO 60 

40 PRINT 'A=B' 

50 GOTO 90 

60 PRINT 'AO' 

70 GOTO 90 

80 PRINT 'A^' 

90 END 

The expression 'A>B ' in line 20 is evaluated using the values input at 
line 10. If the expression is true, a GOTO is executed. If false, the 
next sequential statement is executed, and so on. 

Order of Expression Evaluation 

A numeric expression is evaluated in the order of operator priority. 
This is determined by rules of precedence in BASIC/Wl. These rules of 
precedence are: 

expressions in parentheses 

system and user defined functions 

'' (or **) 

NOT, unary (+,-) 

*,/,MOD 

+,- 

M IN, MAX 

relationals (=,<,>,<=,>=,<>) 

AND 

CR 

Parenthetical expressions are always evaluated first. Then, operators 
with higher precedence are evaluated before operators with lower 
precedence. 
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Example: 

(A + B) /2 

The addition, A + B, being within parentheses, is performed first, then 

the division by 2 is performed, even though the division operator has 

higher precedence. Operators with equal precedence are evaluated from 
left to right. 

Example: 

A+B-C*D*E"F"G 

is interpreted as: 

(A + B) - ((C * D) * (E~(F^G)) 

where the order of operation is: 

1. A-+B, C*D, F'^G 

2. The result of E'^CF'G) 

3. The result of C*D multiplies by the result of step 2. 

4. The result of A+B minus the result of step 3. 
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AND 



B 



A AND B 



TRUE 
TRUE 
FALSE 
FALSE 



TRUE 
FALSE 
TRUE 
FALSE 



TRUE 
FALSE 
FALSE 
FALSE 



OR 



B 



NOT 



A OR B 



TRUE 


TRUE 


TRUE 


TRUE 


FALSE 


TRUE 


FALSE 


■muE 


TRUE 


FALSE 


FALSE 


FALSE 



NOT A 



TRUE 
FALSE 



FALSE 
TRUE 



Figure 11-1 Logical Expressions 
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E valuation of L ogical Expressi ons 

In a logical expression each expression is evaluated as true or false. 
The logical operators determine whether the entire expression is false 
or true: 

Given the values: 

E=0 
A=6 
C=3 
B=2 
D=7 



E AND A-C/3 



A4B AND A*B 



A^ OR C=SINP) 



A OR E 



NOT E 



is evaluated as false since the first term in 
the expression is equal to false. 

is evaluated as true since both terms in the 
expression are true. 

is evaluated as false since both expressions 
are false. 

is evaluated as true since one term of the 
expression (A) is true. 

is evaluated as true since E=0. 

Note 



Logical values can only be used in IF, WHILE, 
UNLESS, or UNTIL st£itements. Expressions such as 
LET A=B<x: or A=B AND C are not legal. 
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INTRODUCTION 

A string is a sequence of ASCII characters. BASICAM string operands 
or data elanents include constants, variables, arrays, matrices and 
functions. String array and matrix operations are covered in Section 
9. String functions are detailed in Section 10. 

String Constants 

A string constant or string literal is a sequence of characters 
enclosed in single quotes or apostrophes ('). All spaces enclosed in 
the quotes are included in the string value. The value of a string 
constant does not change during program execution. The length of a 
string constant ranges from characters (a null string, '"), to 160 
characters. 

Examples: 

'12345.6' 

'I am a string constant' 
' ' (a null string) 
'Columbus, Ohio' 

String Scalar Variables 

A string scalar variable (or simple string variable) is a single letter 
(A-Z) followed either by a dollar sign ($) or by a decimal digit (1-9) 
and a dollar sign ($). String variables represent character strings of 
varying lengths and are initialized to the null value at the beginning 
of the program in which they are defined. Examples of string scalar 
variables are: 

A$ 
X2$ 

The following is a program excerpt using string scalar variables to 
prompt for input: 



12-1 March 1979 



SECTION 12 PCR3058 



Example: 

10 !B$=USER NAME 

20 A$='WHAT IS YOUR NAME' 

30 PRINT A$; 

40 INPUT B$ 

50 PRINT 'WEICCME TO BASIC, ':B$ 

55 END 

>RUNNH 

WHAT IS YOUR NAME 1 BULLWI NIO^E 

WEICCME TO BASIC, BULLWINKIE 

String Subscripted Variables ( Arrays) ; are simple string variables 
followed by one or two values enclosed in parentheses. Subscripted 
variables represent array or matrix elonents. Singly subscripted 
variables, e.g., A$(l), indicate elements in a one-dimensional string 
array, e.g., A$. A doubly subscripted variable, e.g., A2$(l,2), 
represents an elonent in a two-dimensional array or matrix, e.g., A2$. 
In a doubly subscripted variable, the first value represents rows, the 
second, columns. For example, the array location represented by 
A$(l,2) is located in row 1, colunn 2. 

String Arrays and M atrices 

String arrays and matrices are dimensioned and defined by a DIM 
statement or a MAT statonent. See Section 9 for details. For example: 

DIM A$(6) 

defines a one-dimensional array of seven elonents: A$(0) through 
A$(6); 

DIM A2$(3,4) 

defines a two-dimensional array of four rows (0 through 3) and five 
columns (0 through 4) . 

All elements of a string array are character strings of variable 
length. For example: 

10 DIM B$(2,2) 

20 B$(l,l) = 'MICHELt£" 

30 B$ (1,2)= 'BECKY' 

40 B$ (2,1)= 'KAREN' 

50 B$(2,2)='ARLENE' 

55 MAT PRINT B$ 

60 END 

: ^UNNH 

MICHELLE BECK^' 

KAREN ARLENE 
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Naming Variables and Arrays 

String variables and arrays may have the same name in a program, e.g. 
B$. However, the way in vAiich they are defined distinguishes a simple 
variable from an array. For example: 

B$= 'HELLO' 
defines and sets a value for the string scalar variable, B$; 

DIM B$(2,3) 
defines a two-dimensional string array of three rows and four columns. 
The following are examples of string data types: 
Type Examples 



Constant 


'-125' 
•CONSTANT VALUE' 


Scalar Variable 


B$ 


Array or Matrix 


DIM A$(4,5) 


Array or Matrix 
Element 


A$(4,6) 
A${5) 



STRING EXPRESSIONS 

String expressions are constructed of string operands including; 

string variables or array (matrix) elements 

string constants 

references to a string function 
and string operators, including: 

concatenation operator 

relational operators 

logical operators 
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String Operators 

The following are BASIC/VM string operators: 

Operator Meaning 

+ concatenation (combines strings) 

< less than 

> greater than 

equal 

<= I less than or equal 

==< J 

>= 1 greater than or equal 

==> I 

<> I not equal 

AND logical "and" 

NOT logical complemfjnt 

OR logical "or" 

The above operators are the only legal string operators in BASICAM. 
String operators may not be us(?d with numeric operands; similarly, 
numeric operators cannot be used on string operands. 

The Concatenation Operato r; is used to canbine two or more string 
values to produce a single string. 

Exampl e : 



10 A$= 'TODAY IS: ' 

20 PRINT 'ENTER TOCAYS DATE: MONTH Dz^Y YEAR' 
30 INPUT LINE D$ 
40 PRINT B$=A$ + D$ 
45 END 
>RUNNH 

ENTER TODAYS DATE: MONTH Db.Y YEAR 
I JANU ARY 24, 197 9 
TOEAY IS: JANUARY' 24, 1979 
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Logical and Relational Operators ; String data may be used in 
relational and logical expressions just as are numeric data. ILogical 
expressions can be composed of both string and numeric relationals. 

Evaluation of String Relational Expressions 

Comparison of string expressions or values is conducted on a character 
by character basis. Ranking of characters is determined by ASCII code. 
See Appendix B for a complete list of characters and their decimal 
values. If the strings being compared are of different lengths, the 
shorter of the two is padded (internally) on the right with blanks 
until the strings are the same length. The strings are then compared, 
character by character, until the last common non-blank character 
position is reached in both strings. At this point, a decision is made 
on the basis of the relative decimal values of this last character. 

For-example, if the strings 'Z ' and 'AZ' are compared, 'Z ' is 
considered greater than 'AZ' because the decimal value of Z (value: 218) 
is greater than the decimal value of A (value:193). 

Example: 



05 PRINT "THIS IS A CCMPLTTER TASTE ^PEST ' 

10 A$='MICHELOB' 

20 B$= 'MILLER' 

30 IF A$>B$ GOTO 55 

40 PRINT 'MILLER IS GREATER THAN MICHELOB ' 

50 GOTO 60 

55 PRINT 'MICHELOB IS GREATER THAN MILLER' 

60 END 

> RUNNH 

THIS IS A COMPUTER TASTE-TEST 

MILLER IS GREATER THAN MICHELOB 

Lowercase letters have a higher decimal value than uppercase letters. 
For example: 

10 A$='bad' 

20 B$='BAD' 

30 IF A$^$ THEN PRINT 'EQUAL' 

35 IF A$>B$ THEN PRINT 'A$ GREATER' ELSE PRINT 'A$ LESSER' 

40 END 

) ^UNNH 

A? GREATER 



If strings are to be compared on the basis of physical length and not 
relational value, use the LEN function: 
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Example: 

10 A$='HI' 

20 B$= 'HARVEY WALLBAtK^ER' 

30 IF LEN(A$) < LEN{B$) CWTO 60 

40 PRINT 'WRONG' 

50 RRINT 

60 PRINT A$: 'IS SHORTER THAN':B$ 

65 END 

>RUNNH 

HI IS SHCeTER THAN HARVEY WALLBANGER 



Operator Priority 

String expressions are evaluated according to operator priority. The 
rules of precedence are: 

NOT 
+ 

AND 
CR 

Relational operators have equal priority and are evaluated in left to 
right order if more than one appears on a statement line,. 
Parenthetical expressions are evaluated first. Within parentheses, 
evaluation proceeds according to operator priority. For example, in 
evaluating this expression: 

IF A$<^$+(C$(X)4-X$) THEN GOTO 100 

the following steps are taken: 



1. The parenthetical expression (C$(X)+x$) is evaluated. 

2. B$ is concatenated to the result of step 1. 

3. A$ is compared to the result of step 2. 

4. If A$ is less than or equal (on the basis of character 
rank) to the result of step 3, control transfers to line 
100; If the condition is false, control transfers to the 
next sequential statement. 
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CdJVENTIONS 

The conventions for FRIMOS and BASIC/VM system commands are; 



• WORDS -IN-UPPER-CASE 

Capital letters identify command words or keywords. They are to be 
entered literally. If a portion of an upper-case ward is underlined, 
the underlined letters indicate the minimun legal abbreviation. 

• Wbrds-in-lower-case 

Ipv/sr case letters identify parameters. The user substitutes an 
appropariate numerical or text value. Hyphens connecting paraneter 
phrases like the one above, are not literal components of the 
parameter. 

• Braces { } 

Braces indicate a choice of parameters and/or keywords. Uhless the 
braces are enclosed by brackets, at least one choice must be selected. 

• Brackets [ ] 

Brackets indicate that the vrord or parameter enclosed is optional. 

• Hyphen - 

A hyphen preceding a parameter is a required part of that parameter or 
option, e.g, SPOOL -LIST. 

• Parentheses ( ) 

When parentheses appear in a command format, they must be included 
literally. 

• Ellipsis ... 

The preceding parameter may be repeated. 

• Angle brackets < > 

used literally to separate the elements of a pathname. For example: 
<FCeEST>BEBCH>BRANCH537 >1WIG43 > LEAF4 . 
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• option 

The word option indicates one or more keywords or parameters can be 
given, and that a list of options for the particular command follo^^s. 

• Underlines 

For PRIMOS commands only , acceptable command abbreviations are 
underlined in the given formats. 
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ATTACH new-directory 



new-directory is the pathname of the new working directory to which the 
user v\0nts to be attached; iDecomes the current working directory. If 
any directories in the pathname are passworded, the entire pathname 
should be enclosed in single quotes, as in: 

A 'FLOWER STEM>ROSE' 



AVAIL 



disk-nunber 
packname 



Returns the nunber of normalized disk records available on a specified 
disk or the current disk (*) , calculated at 440 wards per record. The 
nijnber of wards per normalized record may not correspond to the nunber 
of wards per physical record on the disk in question. 



BAS.IC V, : : i; pa.t|5t|iaBi j.;v 



Invokes the BASIC/VM subsysten from PRIMOS command level. The system 

responds with the latest revision number and the query, NEW CR OLD:. 

Once a NEW filename or an OLD filename has been entered, the systan 
responds with the BASIC/VM prompt character (>) . 

If the pathname option is given, this command runs the named BASIC/VM 
program and returns the user to HRIMOS command level. 



CNAME oldname newname 



Changes oldname , a filename or the last portion of 
identifying a sub-ufd or file, to newname , a new filename. 



pathname 
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COM IN PUT 



/ pathname 
j - CONTIN UE 
) -END 
\ -PAIBE 






-START 
-TTY 



If pathname is specified, calls in and reads commands from the 
specified file (called a command file) rather than from the user's 
terminal; otherwise, one of the following control options is 
performed: 



- CCMTIN UE 
-START 

-END 
-TTY 



-PAUSE 



Resumes execution of the command file after a -PAUSE. 



Closes command file and causes FRIMOS to resume 
taking commands from the terminal. Either CO -END or 
CO -TTY should be the last command in the command 
file. 

Temporarily suspends execution of the command file. 
Allows commands to be given from the terminal without 
closing the coimand file. 



COMOUTPUT / pathname ^ 
-COMTINUE 
-END 
-NTTY 
-PAUSE 
-TTY 



If pathname is specified, creates a file in which all terminal I/O is 
stored; otherwise, performs one of the following control options: 

-CONTINUE Continues canmand output to pathnane . 

-END Stops commanc^ output to the specified file and closes 

~ command output file units. 



-NTTY 



-PAUSE 



Turns off terminal output. Does not display responses 
to command lines. Terminal output is resumed v*ien 
COMO-TTY cormand is given. 



Stops command output to pathname ; 
command outpjt file remains open. 



ho\>^ver , the 
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-TTY Turns on terminal output, (default) 



•■■(JIRBSt'i : ;|8|thriam!@ : 



Creates a new file directory (sub-UFD) within specified directory. TWo 
files with the same name are not allowed in the same directory. 



■0E!£lTE:'fiiiriai»i 



Deletes a specified file from the current UFD or sub-UFD. filename is 
any existing file or anpty directory to be deleted. If a ufd-name, 
under vvhich there are no files or sub-UFEs, is specified, the entire 
UFD will be deleted. 



LISTF 



Lists all entries under the current UFD, including all directories and 
files. 



LOGIN ■ufd-name 



Allov\B access to files and programs in a specified directory; ufd-name 
is the name of a login directory. The LOGIN cotimand must be typed 
before any interaction with the systan can take place. If no command 
is given and interaction is attanpted, (or if the wrong ufd-name is 
given) , miMOS responds with an error message. To a legal LOGIN 
conmand, ITIIMOS responds with the terminal number, the current time, 
the current date, and finally the miMOS prompt 'OK,' . 
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IJDGOUT 



Terminates all interaction with FRIMOS. 



roiMOS responds to the carmiarid with the terminal nimber , the current 
time of day, and the amount of computer (CPU) time used. 



PASSWD owner- password [nonowner -password] 



Protects the current director/ by specifying owner and nonowner 
(optional) passwords which are required in order to access (attach to) 
the directory. 



PROfEC pathname [owner-rights, [nonowner-rights]] 



Sets protection (access) rights on the file specified by pa thname . 
owner-rights is an integer specifying owner's access rights to the. 
file; nonowner-rights is an integer specifying nonowner 's access 
rights to file. Access rights .are listed below: 

Access Rights 

No access of any kind 

1 Read only 

2 Write only 

3 Read and write 

4 Delete and truncate 

5 Delete, truncate and read 

6 Delete, truncate and wri:e 

7 All access 

Default: Keys are 7 (owner has all rights, 
nonowner has none} . 
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;SiiZfe:i-i^jpttlmi&; 



Returns the size in records (decimal) of a file specified by p athname . 
The nimber of records per file is defined as the number of data words 
in the file divided by 440, rounded up. 



SLIST, pathname 



Displays the contents of file specified by pathname at the terminal. 



SPOOL 



pathname 
-CANCEL PRTxxx 
-LIST 



^^ Pathname is specified, causes the line printer to type out a 
specified file. PRIMOS assigns the file a number in the form PRTxxx, 
where xxx is a nunber between 001 and 200. The -LIST option returns a 
list of all users v\Aiose files are in the queue to be spooled. The list 
includes user name, filename, and file size. The -CANCEL FRTxxx option 
removes file identified by PRTxxx from the spool queue. Binary files 
cannot be spooled. Files are printed according to the time the file 
vnQS spooled or according to file size. 



ALL 
DISKS 
STATUS< NEWCRK 
_UNITS 
USERS 



Returns systan status information indicated by specified options. ALL 
returns all information, including disk names and physical-to-log ical 
disk correspondence (DISKS) , network information (NETWCHK) , user 
information (USERS) , and nunber of open file units on the current disk 
(UNITS) . 
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TERM [option (s)l 



The most commonly used options are: 

-ERASE character Sets user's choice of erase character in place 
of the default, ". 



-KILL character 



-XOFF 



-NOXOFF 
-DISPLAY 



Sets user's choice of kill character in place of 
default, ?. 

Enables X-OFF/X-ON feature Wiich allows programs 
to halt without returnii^g to FRIMOS ccxnmand 
level. Programs can be halted by hitting 
CONTROL. Programs may be resuned at point of 
halt by hitting CONTROL-Q. Also sets terminal 
to full duplex (default value) . 

Disables X-OFF/Xhdn feature (default) . 

Returns currently set values of erase and kill 
characters. Also displays current duplex 
setting. Break and X-ON/X-OFF status. 



If no options are specified, the TERM command will return a complete 
list of TERM options. See ^^pendix D. 



USERS 



Returns the nunber of users logged into FRIMOS at any given time. 
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The following is an alphabetized description of all BASIC/VM system 
commands. Commands are issued at BASICV command level, in response to 
the BASICV system prompt character, *>'. Each command must be typed in 
upper case and cannot be abbreviated. Some commands may also be used 
as statements and are appropriately indicated. 



ALTER line-number 



Enters an editing mode to allow modification of indicated line. 
Editing subcommands, listed below, are entered in response to the 
special ALTER mode colon (:) prompt. More than one such command can 
be packed into a single line; no delimiter is necessary. The colon 
prompt is returned until QUIT is typed. 



Subcanmand Effect 

Vstring/ ;^pend string to end of line. 

Bnn Move pointer back nn characters (vihere nn is any integer) . 

Cc Copy line up to but not including c (vvhere c is any 

character) . 

Dc Delete line up to but not including c. 

En Erase n characters. 

F Copy to end of line. 

I/string/ Insert str ing at current position, (the slash may be any 
delimiter not used as part of the string. 

Ml Move n characters. 

N Reverse meaning of next C or D parameter (copy until 

character =<c, or delete until character =>c) . 
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0/ string/ Overlay string on line from current 

position. A '!' changes a character to a space, 
a space leaves character unchanged. 

Q Exit from Alter mofe. 

iVstring/ Retype line with s tring fron current 

position. (Similar to CVerlay but '!' and space 
have no special effects.) 

S Move pointer to start of line. 



ATTACH pathname 



Attaches to directory specified by pathname ; may have one of the 
following formats: 

Format 1: *> sub-uf d-name 

v^ere ^ indicates the current directory 

Format 2: i <*> | ufd-na:ne[> sub-uf d-name] 
<disk> I 

where <disk> is the logical disk number on v*iich 
directory named by ufd-name is located. <*> indicates 
current disk. More than one sub-ufd-name may be 
indicated if sub-ufds are nested. 

Format 3: ufd-name [> sub-ufd-name] 

v\^ere directory named by ufd-name is located on the 
current disk. 

Example : 

ATTACH<6>MANUALS>REV16>PRCGC0MP>BASICV 

Although similar to the HRIMOS ATTACH comiand, this canmand may not be 
abbreviated and is issued at EASICV command level. If directories are 
passworded, the passwords must be included. 
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BREAK I ON 
i OFF 



lin-num-1 [ , . . .lin-num-n] 



Sets and unsets breakpoints at specified statement lines for debugging. 
line-1 through line-n are statements at vhich the program is 
instructed to stop. A maximan of 10 may be set. The IBPS command 
returns a list of all currently set breakpoints. 

If a statement line at v*iich a breakpoint is set is reached during 
execution time, the program stops and returns to BASIC/VM comnand 
level; type CONTINUE to resume execution. BASIC/VM resumes execution 
with the statement specified by BREAK ON, and continues until the next 
breakpoint, STOP, END, or error is encountered. 

If statement numbers are not specified with BREAK OFF, all previously 
set breakpoints are automatically turned off. 



CATALCX5 [opt ion (s)] 



Lists all filenames under the current UFD, plus option information, if 
specified, opt ion (s) are any or all of the following: 



DATE 



Returns the date and time of files' last modification. 



PROTECTION Returns the files' protection attributes (owner and 
~ nonowner rights) . See Section 2. 



SIZE 
TYPE 

ALL 



Returns the size of each file in records. 

Indicates wtiether the file is SAM, mM, SEGSAM, 
SEGDAM, or a UFD. 

Includes all of the above information. 



If no options are specified, CATALOG returns only the filenames. 
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CLEAR 



Resets all previously set numeric or strirg variables to zero or null 
respectively. Also deallocates previously defined arrays and closes 
all open files. Useful in Iimiediate mode calculations. 



ca>ilNP j pathname 
COMTINUE 
PAUSE 
TTY 



Opens and reads commands in coimand file of specified pathname. If 
control options (CONTINUE, PAUSE) are specified, coimand file halts at 
COMINP PALBE, resumes with COIINP CONTINUE. Commands in this file are 
executed until a COMINP TTY command is reached. Ihis is generally the 
last command in the COMINP file. CCMINP may also be used as a 
statement; see Section 15. 

NOTE 

As a ccmmand, CCMINP takes an unquoted argunent: 
as a statement, it takes a legal BASIC string 
argument. 



GQMPIIJE [pathnane] 



Translates the foreground source program into an executable binary 
program (machine language) v*iich can be named and saved by specifying 
pathname . This binary file c;jn be executed directly by specifying its 
pathname with EXECUTE. See EXE:CUTE. If the filename (pathname) is 
oTiitted, the system compiles the code into user manory for use with 
EXECUTE but no binary file is saved to disk. COMPILE also displays at 
the terminal any syntax errors (e.g., bad statatient format, 
misspellings, etc) that may occur in the program. These are knovvn as 
'compile-time' errors, as distinguished from 'run-time' errors which 
occur during program execution. 
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CONTINUE 



Resumes program execution after a PALBE or a breakpoint. 



DE££TE I lin-num-l|j . . .lin-num-n] 
llin-nun-1 - lin-num-n 



Deletes the specified statanent lines from program. 1 in-num-1 through 
lin-num-n are statonent numbers to be deleted. Statements may be 
listed individually, separated by commas (as in first format) , or they 
may be specified in a range (as in second format) , the beginning and 
end of vAiich are separated by a dash, as in 10-300. 



EXEGUTE Up^thname] 



If no pathname is specified, the currently compiled code in user memory 
is executed. If none exists, the foreground source file is translated 
into executable machine language and then executed. When a binary file 
pathname is given, the binary file is immediately executed. If a 
source file is specified, it is first compiled into machine language 
and then executed. EXECUTE also displays at the terminal any run-time 
errors that may occur during program execution. Run-time errors are 
usually logic or control errors v*iich interrupt or inhibit program 
execution, e.g., a READ after a WRITE to a sequential file. 
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I lin-r 
llin-r 



EXTRM^T I lin-num-l[j . . . 1 In^num-n] 
-num-1 - lin-num-n 



Deletes all except the specified lines. 1 in-nun-1 through 1 in-nun-r t 
are statement nunbers to be saved. Statements may be listecl 
individually separated by commas, or they may be specified in a range, 
the beginning and end of which are separated by a dash. The statenent 
nunbers must be in ascrending order. 



FILE [pathname] 



Saves all input and modifications to current file under original name 
(default) , or under new name specified by pathname . 

When filing a program, there aire several points to remonber: 

1. If a pathname is not specified, BASIC/VM automatically uses the 
name of the foreground file. 

2. If a pathname different ::rom the original name is specified, you 
will have two versions o:: the same file. If the pathnane already 
exists, BASIC/VM returns the prompt: 

OK TO REPLACE: 

All responses other than Y, YE, YES or OK, are interpreted as NO, 
and BASICV requests another pathname. 

3. A program need not be complete to be FILEd. It is advisable to 
FILE from time to time to avoid losing file modifications due to 
an inadvertent typing error. However, be sure to FILE a modified 
program before calling in another file or exiting the systan, 
lest it be overwritten, truncated or generally garbled. 

LB PS 

Lists currently set breakpoints. Breakpoints can be set by the BREAK 
ON ccximand. 



REV. ].4 - 6 



PDR3058 BASIC-VM SYSTEM C0MP4ANDS 



:mm$;^ 



Reports the number of statements in the current program. 



LIST [NH] 



(lin-num-l[j.. .lin-num-n]]"] 
llin-num-l - lin-num-n M 



Displays the contents of the foreground file at the terminal. NH 
option suppresses program header (date, title etc) . lin-num-1 through 
lin-num-n are statement nunbers vhich may be listed individually with 
command separators, or specified in a range, the beginning and end of 
vvhich are separated by a dash. 



i;(|||i|j!:;pfij|i^ 



Merges external file, specified by pathname, with foreground file. 
Line numbers in the external file which are duplicated in the 
foreground file are overwritten by those in the external file; 
otherwise, lines are inserted or appended in numerical sequence. 

If the specified file is binary, it is loaded into user memory but does 
not beccme part of the foreground file. After a binary file LCAD, an 
EXECUTE with no pathname will run the just-LOADed binary file. 



^iMWlfpafeihriiiftel 



Indicates to BASIC/VM that a new foreground file is to be created with 
the specified name. All lines previously in the foreground are erased. 
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OLD [pathname] 



Calls an existing file, identi;:ied by pathname , to the foreground. The 
last component of the pathnamo is the name of the file being called to 
the foreground. In the followi.ng example, STARTREK is the file called 
to the foreground: 

OLD GAMES >basic>junk>star'::tiek 



PURGE [pathname] 



If pathname specified, deletes indicated file from directory. 
Default: deletes the disk copy of the foreground file. A file 
currently open cannot be PURGEd. 

After the PURGE command is issued, the file remains in foreground until 
another file replaces it. PUFIGE can also be used as a statanent; see 
Section 15. 



QUIT 



Returns control to FRIMOS from BASIC/VM command level. Uhlike CTRL-P 
and BREAK, QUIT closes all files opened by BASIC/VM , and deletes 
temporary files created by BA,S.:C/VM. 
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RENAME neWname 



Changes the name of the foreground file, but does not rename the 
original disk copy of the file. If the renamed file is FILBd, two 
copies of the file will exist with different names. The renamed file 
will not be saved unless it is FILBd. 



RESEQUENCE [new-start] [ ,old-start] [ ^ew-incr] 



Reniitibers statements in the foreground program. new-start is the 
number which begins the new sequence. (Default: 100) . old-start is 
the existing line nutiber at which to begin renimbering. (Etefault: 
lowest nunbered line) . new-incr specifies increment value. (Default: 
10) . 



RUNiNH]: [lin--num] 



Begins compilation and execution of the foreground source program, at 
lin-nun , if specified. No binary file is stored by the RUN process. 
NH suppresses the program title, date and time usually displayed at 
Tun-time. RIN also displays all compile-time errors (statement syntax, 
spelling, etc) and run-time errors (faults in program logic) that may 
occur during program translation and/or execution. 
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TRACE foti 
[ OFF 



Displays in brackets all statement nunbers as they are executed until 
the TRACE OFF command is typed. The statonent nunbers may be stored in 
a separate file (see the FRIMCS command CCMOin*, /Appendix D) . TRACE Ob] 
is issued immediately after compilation (COMPILE) and immediately prior 
to program execution (EXECUTE). Used to examine program logic or 
control. 



TYPE pathname 



Displays the contents of the specified non-foreground file at the 
terminal, but does not replace the file currently in foreground. 
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The followirq is an alphabetized description of all BASIC/VM statanents 
and their formats. Conventions are the same as for BASIC/VM system 
ccmmands in Section 14. No abbreviations are accepted and all 
statanents must be typed in upper case. Statements \n^ich can be used 
as conmands are so indicated. 

BASIC/VM Conventions 

All FRIMCS command conventions, as listed in Section 2 or Section 13, 
apply also to BASIC/VM comnands and statements. In addition, the 
following parameter representations are used throughout this section: 

arg function argunent 

con constant (numeric or string) 

(dim) dimension for array or matrix; a numeric item 

expr an expression; i.e., a combination of operands and 

operators vrhich can be evaluated. Can be either 
numeric (num) or string (str) . 

str string 

var variable 

unit file unit number (a numeric constant) on vvhich file 

is opened for reading and/or writing* 
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(PRIM<EY \ 
KEY ze::o~iSKpr\= str-expr-2 keylist 
KEY ) 

v\*iere keylist = [,KEY nuin-expr-1 = str-expr-3]* 



Adds record, str-exp:-l , to MIDAS file, opened on unit. A primary key, 
PRIMKEY, KEY zero-exp: or KEY and its value, str-expr-2 , must be 
supplied. One or more secondary keys may be specified in keylist, 
v*iich contains the names, num -expr-l , and value(s) , str-expr-3 , of the 
secondary key(s) . ^ indicates repetition of expression as necessary. 



CHAIN pathname 



Closes all open files and transfers program control to external program 
specified by pathname. 



Cfi^NGE num-array TO str-var 
CHSlIMGE str-expar TO num-array 



Transforms ASCII character string , str-expr , into a one-dimensional 
nuneric array ( num-array ) containing the decimal values of the ASCII 
codes of the string, or transforms a numeric array of ASCII codes to 
its string equivalent, str-va r . ASCII characters and their decimal 
equivalents are listed m ^^pemdix B. For exanple, when A$= 'WORD' is 
changed to array A, A(0) contains the length of A$, or 4; A(l) 
contains the decimal code of W, i.e., 215, etc. Conversely, if array A 
is changed to A$, the resulting string length is controlled by the 
value in A(0) . 
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CLOSE # uni t-1 [ , . . . uni t-n] 



Closes file previously opened on unit by a DEFINE FILE statement, unit 
is maximun of 12. 



;Ci&^&j5|dt^iie!- ■ TO ^fi&^^^ 



Changes name of specified file, oldname is the pathname of the file to 
be renamed; newname is the new pathname or filename given to the file. 






stops execution of current program and executes commands from command 
file specified by pathname . CCMINP PAUSE and COMINP CONTINUE 
temporarily halt and restart the command file respectively. Commands 
in file are executed until CCMINP TTY, the last command in the file, is 
reached. Also used as a ccanmand; see Section 14. 



Bl|(Vi-:t'lsefn-l i>-i'.-.iterli>-n}' 



Lists numeric and string constants to be accesed by a READ statement. 
For example, given the following READ and D^TA statements: 

DATA 12, 45, 'BULL' 
READ A, B, C$ 

The variables A, B and C$ will be assigned the values 12, 45 and BULL, 
respectively. There may be any nutiber of EATA statements within the 
same program. 
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DEFINE 



READ 
APPEND 



FILE iunit = filename [ ,type-cx)de] [, record-size] 



Opens file, named by f ilena me^ a string expression, on specified unit. 
Optionally assigns file type and access method, indicated by type-code . 
Type-codes are listed in Table 15-1, following. If no type-code is 
given, the default (ASC) is assjned. The default record length oF" 60 
words (120 characters) may be increased or decreased by specifying 
rec ord-size , (a numeric expression) in nuriber of words. For MIDAS 
TiTes, record-size should be set equal to the combined length of the 
data record and the primary key; this is specified during CREATK when 
the template is being created. A::cess may be restricted to read or 
append only with the READ and APPEND options respectively. A file 
DEFINBd as a READ file is assiirnad to exist. 



DEFINE SCRATCH FILE #unit [,fil.2!-type] [, record-size] 

Opens a temporary file on specified unit , of any type except MIDAS. 
When unit is closed, the scratch file is automatically deleted. 



DEF FN var [ (arg-l , . , .arg-n) ] = expression 



Defines a one line function named by var , a string or nuneric variable, 
(No FNEND statement necessary.) Argunents ( arg-l to arg-n ) are nuneric 
or string scalar variables only. 



DEF FN var [ (arg-l,... arg-n)] 



FNEND 



Defines a user-defined nuneric or string function, of one or more 
lines. The last line must be F1>JEND. var is a simple nuneric or string 
variable, arg-l to arg-n are dimmy arguments for the function; may be 
numeric or string scalar variables. The defined function is not 
executed until it is referenced in the program; control then shifts to 
the function definition until FNEND is reached. 



REV. 15 



PDR3058 



BASIC/VM STATEMENTS 



Table 15-1. File Type-Codes 



Access 
Type-Code Method 

ASC SAI^l 

(default) 



ASCSEP SAM 



ASCLN 



SAM 



ASCEA 



EftM 



BIN 



SAM 



BINDA 



SEGDIR 



DAM 



SPECIAL 



Contents 

ASCII data, formatted like tenninal output, 
using BASICV PRINT conventions, e.g., 
commas, colons and semi-colons, all dictate 
the appropriate nunber of spaces to be used 
as data delimiters. Records variable- length 
and easily inspected. 

ASCII data stored with commas inserted 

as data delimiters. Data are stored 

and read back exactly as entered. 

Records fixed-length, accessed sequentially. 

ASCII data with comma delimiters, 

and line numbers inserted in increments 

of 10 at the start of each record. 

Designed to be edited at BASICV command level. 

Similar to ASCSEP. Records fixed-length 
and blank-padded as necessary. Direct access 
method used for quick, random access to 
any record in the file. 

Data storage transparent to user. 
Records are fixed-length, accessed sequentially. 
String data stored in ASCII code: numeric data 
stored in four-viord floating-point fonti. 
Provide maximum precision and compactness of 
nuneric data, but cannot be inspected by TYPE etc, 

Same as BIN but direct access method 
is used for randan record access. 
Ftecords not data-filled are zeroed out. 

Identifies file as a segment directory. 
Subordinate files, identified by number, 
may be SAM, DAM or other SBGDIR files. 
An additional DEFINE is required 
to access a subordinate file. 



MIDAS SPECIAL Multiple Index Data Access files. 

Created by Prime-supplied MIDAS utilities. 
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DIM V a r I ( nun- con) 

[(num-con-r-l, nun-con-2) 



li 



Defines the dimensions of a nurieric or string array or matrix, named by 
a numeric or string variable, var . Dimensions are represented by 
( num-con) and ( num-con-1 , ni iin-con-2 ) , nuneric constants. Default: 
(10) or (10,10) . Variables are not legal dimension specifiers in DIM 
statonents. The lov«st eleiTient of an array is always (0) or (0,0). 
Arrays and matrices may be redimensioned within a program with the MAT 
statement. 



DO 



t)OEND 
•ELSE DOn 



,DOENb 



Sets up a series of statements in association with IF-THEN statements, 
executed if a specified condition is met. DOEND indicates the end of 
the series. ELSE DO is an optional alternative to previous set of DO 
statements. ELSE can also be used in conjunction with IF. (See IF 
statement). Dots (.) represent statements in program. 



END 



Terminates program execution: serves as messageless STOP. 
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EOTER,- fcM#r-|irn.|:|>: : i|:|n^pi^ii:; |-: f ^fe- 



Allows a specified nunber of seconds, time-limit , (range 1 to 1800), 
for user input of a value for a nuneric or string variable, var . No 
prompt is given, time-var , a nuneric variable, returns the actual time 
taken to enter value. Cnly one value can be entered from the terminal. 



'iiSER''%: '04£^n&^^' 'i0!m:AMii^^ 



Returns user number assigned at LOGIN in a numeric variable, 
user-num-var. Other options are same as for ENTER. 



ERRGR OFF 



Turns off all error traps in conjunction with the OSI ERRCK GOTO 
mechanism. 



ftoS ij M$X^ 'iiSt^rtt'^' \ ## -rllTEfe- %pip]". 



Specifies beginning of loop. Used with NEXT statement. The loop 
index, which changes during program execution, is specified by index , a 
nuneric variable. The initial value of the index is set to start , a 
nuneric expression; the incranent value is set by incr ; and the final 
value of the index is represented by end, a nuneric expression. When 
the index attains this value, loop execution stops. 
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FOR index = start [STEP incr] I WHILElcondition-expr 



UNTIL] 



Specifies the beginning of a loop with statement modifier. Used in 
conjunction with NEXT. conc i i t ion-ex pr , a conditional expression, 
determines how long the loop will be executed. The WHILE modifier 
indicates that loop execution will continue as long as the specified 
condition remains true. UNTIL specifies that loop execution will 
continue until the specified condition is met. start represents the 
initial index value; incr optionally sets the increment value. Ihe 
default STEP size is zero. The following are examples of legal and 
illegal loop nesting. Example of legal nesting techniques are shown 
first: 



Two-level Nesting 

FOR II UNTIL 11=13 
FOR 12 = 1 TO 13 



NEXT 12 
NEXT II 



Three- 1 ev el tfesting 

FOR II = 1 TO 10 
FCR 12 = 1 TO 10 
FOR 13 = 1 TO 10 



NEXT 13 
NEXT 12 
NEXT II 
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Examples of unacceptable nesting techniques are: 
Two-level Nesting 

FOR II UNTIL 11=13 
FOR 12 = 1 TO 10 



NEXT II 
NEXT 12 

Three-level Nesting 



FOR II = 1 TO 10 
FOR 12 = 1 TO 10 
FOR 13 = 1 TO 10 



NEXT II 
NEXT 12 
NEXT 13 



Note 

The statement modifiers WHILE, UNTIL and UNLESS may 
be used with other executable statanents as well. 
Note that UNLESS may not be used with FCR loops. 



GOSUB lin-nun 



Unconditionally transfers program control to an internal subroutine 
beginning at specified lin-nu n. A RETURN must be executed to terminate 
the subroutine. Up to 16 GOSUB statanents may be nested. 
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OOTQ lln-nurtr 



Transfers program control forvard or backward to a specified lin-nun., 
A loop may be created vAien the specified line number appears prior to 
the GOTO statanent. May be used with IF. 



IF expr 



GOTO lin-num-1 
THEN lin-num-1 
THEN statement-1 



ELSE 



j staten 
I lin-ni 



statement-2 
ium-2 



Transfers program control depending on the value of a relational, 
logical or nimeric expression ( expr ) . lin-nun is the statement niEnber 
to Oiich parogram control is transferred if the expression is true. 
statement-1 is executed if the preceding expression is true. If the 
expression is not true, either statement-2 will be executed, or control 
will transfer to lin-num-2 , depending on which, if any, is specified. 
If expr is not true, ana' no alternative is provided, the next 
sequential statement is execut(K3. 

IF statements may be nested to any level . IF may be used in one of the 
following canbinations: 



1. IF expr 



GOTO line 
THEN line 
THEN statement 



[else (line 1 
|_ \ statement / 



IF condition THEN DO 



DOEND 
r- ELSE DO-, 



■- DOEND -■ 
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INPUT ['prompt-string',] var-l|^. . .var-n J 



Prompts user for input specified by var-1 through var-n vhich are 
either nimeric or string variables or array elements, separated by 
cOTimas. If no prompt string is provided, the default prompt character 
(1) is given; otherwise, the string is printed. 

Trailing ccanmas are ignored as are data in excess of variables 
specified. Data must be input in the same order in vhich the variables 
are given and must also match the variable type, or an INPUT D^TA ERROR 
will occur. 



INPUT LINE ['prompt-string',] str-var 



Prompts user, with optional ' prompt-string ' , for str-var , a string 
variable or string array elanent. Accepts entire input line, including 
colons, commas, and leading blanks as one entry. 



■itiijr!i:;:i«^jci*!:^^ 



The assigrment statanent, used to assign values to nimeric or string 
variables or array elonents; the keyword LET is optional, var 
represents a nimeric or string variable or array element. expr is 
either a nimeric value, string expression or another variable. 



MARGIN fval ue \ 
ioFF I 



Sets nimber of characters per line to value , a nimeric expression. 
Range is 1 to 32767; the default is 80. MARGIN OFF turns off all 
margin settings other than the default. 
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MAT mat 4 



ZBR 
CON 
IDN 
NULL 



(dim-l) 
(dim-l,dlm-2) 



Sets initial valu, of matrix elements to zero, one, identity or null, 
respectively. Also used to rtKJimension a one-dimensional matrix to 
( dim-l ) , a numeric expression, or a two-dimensional matrix to 
( dim-l ,dim-2 ) . NULL can only be used on string matrices; it 
initializes all elements to a null value. IDN transforms a matrix into 
an identity matrix, one in \hich all elements, except those on the main 
diagonal, are 0; the main diagonal elements each have a value of one 
(1). ZER initializes all matrix elements to zero. CON sets all 
elements equal to 1. 



MAT mat-3 = inat^lj -Jmat-2 



Adds, subtracts or multiplies the elements of mat-1 and mat-2 to form a 
target matrix, mat- 3. In multiplication, the target matrix dimensions 
are the number of rows of mat-1 and the nunber of columns of mat-2. 

Rules: 



For addition and subtraction, the two matrices must have the 
same dimensions, e.g., DIM A(2,2) , DIM B(2,2) . 

Ebr multiplication, tne number of columns in the first matrix 
must equal the numlDer of rovss in the second matrix. The 
result will be a matrix with the dimensions of the number of 
rows of the first matrix by the number of columns of the 
second matrix. 

A matrix may not be multiplied by itself; nor can the current 
value of the target matrix (the one appear irq on left side of 
equation) be used in the multiplication expression. Fbr 
example, MAT A= A*C is illegal. 
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MAT mat-1 = (expr) * mat-2 



Multiplies each element of mat-2 by a specified nuneric value ( expr ) 
and assigns results to mat-1 . If mat-1 is an existing matrix, its 
elements will be redefined, and its dimensions will be changed to those 
of mat-2. 



MAT mat-1 = IN V (mat-2) 



Assigns the inverse values of a square matrix mat-2 , (determinant not 
equal to 0) to the target matrix, mat-1 . The resulting values in mat-1 
can be multiplied by mat-2 to yield the identity matrix in which all 
elements are equal to 1. 



MAT mat-1 = TRN (mat-2) 



Calculates the transpose of the values of mat-2 and assigns them to 
target matrix mat-1 . A matrix is transposed by rotating it along the 
main diagonal. For example: 



14 7 

2 5 8 

3 6 9 



12 3 
4 5 6 
7 8 9 



mat-2 



mat-1 =TI^ (mat-2) 



MAT INPtjr['' prompt-string' ,] mat-1 [, mat-2] 



mat(*) 
, . . .1 mat-n 



Reads data from the terminal and assigns the values to specified 
matrices, mat-1 through mat-n . mat (*) indicates that elements may be 
input until a new line is typed. Matrix is autanatically dimensioned 
to number of input elanents. Default prompt character is !, unless 
pronpt-string is specified. The type of data input must match the 
matrix type (i.e., nuneric or string). 
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MAT PRINT mat-1 [,...mat-n] 



Prints indicated matrices, mat-1 to mat-n, at terminal. If a matrix 
name is follov\ed by a colon instead of a comma, the elanents will be 
separated by spaces instead of colunm tabs vv*ien printed. If more than 
one matrix is listed, each begins on a new line. Commas are the only 
delimiters v\hich put matrix elonents into columns, i.e., all colunns, 
or one print zone, apart. If .NL. (new line) is typed after each 
input, output will occur in row order. 



ma READ raat-1 [ , , '. .mat-n] 



Reads values from a data list and assigns than to the elanents of the 
specified matrix or matrices. Values are assigned until all matrices 
are filled, or the data list is exhausted. 



jMAT READ [*J # uinlt , ma t-i I , » , .ttia t-nj ^ 



Reads data items from an external file opened on unit and assigns them 
to elements of specified matrix or matrices. Optional * indicates that 
all data from current record diould be read before a new record is 
read. 



MAT WRITE funlt^ raat-^1 [,.. .n\at-nj: 



Writes an entire matrix or matrices to a file on the specified unit . 
If matrix names are followed b/ colons instead of commas, elements of 
the matrices are output one space apart instead of 21 spaces (one print 
zone) apart. 
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If two units have been opened, a matrix may be read fran one unit and 
written to the other. Ebr example: 

MAT READ #1, A 
MAT WRITE #2, A 



NEXT him--var 



Defines the end of a loop beginning with a FCK statemoit. The num-var 
matches the variable used with the ccxnpanion FOR statement. 



:CB:;;niitt-^i^ •<30SWB ;:|^tn-'iiiuaft^.y-.,:,l1tonn 



Transfers program control to a subroutine at a specified line nunber 
depending upon the value of the numeric expression, nun-expr . When a 
RETURN statanent is reached in the subroutine, control returns to the 
statonent following the CN...GOSUB statement. 

The value of the numeric expression must be less than or equal to the 
number of statement lines listed. Thus, if the value of the expression 
is 1, control will be transferred to the statainent indicated by 
1 in-nun-1 . If the value is n, control will be transferred to the 
statanent indicated by lin"-nun-n . If the value of the expression is 
out of range, an error message will be displayed. 



#1 'niin^ifei^pf- iOTG'-' iaM?^ftyiii^:,>:.n,.lln-- 



Transfers program control to one of a list of line numbers (lin-num-1 
to lin-num-n) depending on the value of the numeric expression, 
num-expr . IF the value of num-expr is 1, control transfers to the 
first line nunber given, 1 in-num-1 ; if the value is 2, control 
transfers to the second line number given, and so forth. The value of 
num-expr must be less than or equal to the number of statement lines 
listed. If the expression value exceeds the number of lines listed, an 
error message is displayed. 



15 - 15 March 1979 



SBCTIOSI 15 PIH3058 



ON aro #unit ODTO lin-num 



Establishes a line number to wtiich program control will transfer vhen 
an END OF FILE occurs on specified unit . This statement does not test 
for END OF FILE; instead, it establishes the action to be taken v^en 
the end of the last record in a file is reached during a READ, 
POSITION, or other I/O operation. 



ERROR ODTO lin-huti 



Establishes a line nunber to \*ich program control will transfer when a 
run-time error occurs. Two variables, ERR and ERL, and the function 
ERR${num-©cp:) , are associated with ON ERROR GOTO. 

ERR Variable set to the code number of the error 

which activated the CN ERROR statement. 



ERL 



Line number being executed vsten the error 
occurred. 



ERR$(num-expr) Outputs actual text of the error message 

associated with an error code represented by a 
numeric expression, nun-expr . 

The ERRCe OFF statement can be used to cancel all error traps set by ON 
ERRCH GOTO statements. See ERROR OFF. 



ON ERROR #unit GOTO lin-num 



Establishes a statement line to \Ahich program control will transfer 
vihsn an I/O error occurs on tiie specified unit , e.g., v*en an invalid 
number is entered. 
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PAUSE 



Acts as an executable BREAK command. Suspends program process at 
v\*iere PAUSE occurs. To resume program, type CONTINUE. 



line 



POSITION If unit TO reco)?d-riutvber 



In direct access files (ASCEA, BINDA) , positions the internal record 
pointer to a specified record-number in a file on the specified unit. 
When pointer is positioned past last record, the ON END #unit GOTO 
statanent is activated (if specified) or the error message, END OF 
FILE, is displayed. 



: :■■ .■(:■■ ^■... : SEQ^ 
POSITION #:unie:> mil tnum-exprj ^ str-expr 

I. . ■ -SAME KEY-^ 



Positions a file read pointer to a specified record in a MIDAS file. 
If a secondary key number, nu m-expr is not indicated, num-expr = is 
assuned. If SEQ is supplied in lieu of key, the pointer positions to 
the next sequential record SAME KEY positions to datum only if next key 
matches current one. POSITION is similar to READ except that no data 
is retrieved. 



PRINT 



item-1 



LIN\ ~] 




[7 ^-^H "1 




TABl(num) 


:i,..,.ttenHrt, 


tee Ichiro) 




|SPaJ . 




I SPAl 




^ ' _i 




L J 


_ 



Item-1 to item-n 



Prints formatted information at the terminal. _____ 

represent nuneric and/or string values. 

LIN forces the specified number ( num ) of carriage return - line feed 
combinations between items in the output if nun is greater than 0. If 
nun is less than 0, it forces that many line feeds only: if num = 0, 
only a (CR) is generated. 
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TAB forces tab to specified colunn nimber. SPA forces number (nun) of 
spaces bet\*een items in output. 

A comma in a print list causes the terminal to advance to the first 
character position of the next print zone. Each print zone consists of 
21 character positions. rf data will not fit on one line, it is 
continued on the next line. If a colon is used instead of a comma, the 
itans are separated by a single space in the output; if a semicolon is 
used, no spaces are inserted between items. 

Wien a nuneric expression is printed, if the value of the expression is 
positive, the sign is suppressed. If the value of the expression is 
negative, a minus sign is printed for the sign character. 

If used without any parameters, the miNT statanent causes a blank line 
in the output. 



PRINT USING format-string, iten-lj; . ..iton-n] 



Generates formatted output according to format characters in 
format-string , including a dollar sign, plus or minus signs, decimal 
points and right-left justification. Item-1 through iton-n represent 
string or nuneric values. Format characters listed in Table 15-2. 
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Table 15-2. Nuneric Ebrmat Field Characters 



Sample 
Item: 



Using this format Will be 
Specification : printed as : Ranar ks : 



POUND SIGN FOFMAT SPECIFICATIONS (#) 



25 



-30 



1.95 



598745 



##### 
##### 



##### 



25 



30 



***** 



Digits right justified 
in field with leading 
blanks 

Sign is ignored because 
item is positive. 

CSily integers are 
printed; the 
number is rounded 
off. 

If number is too large 
for the specified 
field, asterisks 
are printed. 



PERIOD (DECIMAL POINT) FORMAT SPECIFICATIONS ( .) 
20 #####.## 20.00 



29.347 
789012.344 



#####.## 
#####.## 



29.35 
***** 



Positions to right of 
decimal paint are 
zero filled. 

Itan is rounded off. 

If nunber is too large 
for the specified field 
asterisks are 
printed. 



CCMMA FORMAT SPECIFICATIONS ( ,) 
30.6 +$,###.## 



2000 



#,###. 



+$ 30.60 A space is substituted 
for comma v^dien the 
leading digits are blank. 

2,000. Conma is printed in 
indicated position. 
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00033 ++##,### +00,033 Comma is printed 

v*en the leading zeros 
are not suppressed. 

VERTICAL (UP ARROW) FORMAT SPEC IT ICAT IONS C) 

170.35 +##.## +17.03E-f«l 

1.2 +##.## +12.00E-01 

6002.35 +###.## +600.23E4B1 



Note 

If more than four up arrows are used, the 
corresponding nunber of exponent digits will be 
printed. 



PLUS SIGN FCRMAT SPECIFICATIONS {+) 

20.5 +##.## +20.50 Plus sign printed v^ere 

indicated; item is 
positive. 

1.01 +##.## + 1.01 Leading zero's print as 

blanks. 

-1.236 +##.## - 1.24 Minus sign printed When 

vhen iton is negative. 

-234.0 +##.## ***** If number is too large 

for the specified 
field, asterisks 
are printed. 



MINUS SIGN FOR^T SPECIFIC AT I ONE". (-) 

20.5 ###.##- 20.50 Sign discarded if item 

positive. 

000.01 ###.##- .01 Leading zeros 

immediately to the 
left of the decimal 
point are suppressed. 
Minus sign not printed 
when item is positive. 
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-234.0 
-20 

-200 



.## 

.## 

.## 



234.00- Sign printed where indicated. 

-20.00 Floating minus signs 
are treated as digit 
positions. 

****** Number does 

not agree with the 
format; asterisks 
are printed. 

2.00 Itan is positive; 

minus sign suppressed. 



DOLLAR SIGN FORMAT' SPECIFICATIONS ($) 



30.512 


$###.## 


$ 30.51 Dollar sign printed 


-30. 512 


$###.##+ 


$ 30. 51 -Negative item; minus 
sign printed v^iere 
indicated. 


13.20 


+$$$$#.## 


+ $13.20Floating dollar sigi 



printed immediately 
prior to leftmost 
significant digit. 



Table 15-3. STRING FOPMAT FIELD CHARACTERS 

POUND SIGN (#) AND ANGLE BRACKETS (<,>) FORMAT SPECIFICATIONS 

Will be 

printed as : Remarks 

TWELVE Right-justified 

TWELVE left-justified 

GFIAN Only 4 characters 

will fit into 
specified field, 
field. 



Sample 


Using this format 


item: 


specification: 


TWELVE 


>###### 


TWELVE 


<###### 


GRAND 


#### 
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READ var-l[j . . .var-n] 



Reads numeric or string values Erom one or more CftTA statanents within 
the program, beginning with the lowest nun±)ered one. var-1 through 
var-n are string or nuneric variables separated by commas. Begins 
accepting values with first item in lowest numbered DATA statement. 
READ is alv«ys associated with one or more DATA statements. If the 
data items are exhausted before all variables are satisfied, an error 
message is displayed. The RESTCX^E statement may be used to recycle 
data values within a program. 



READ [KEY] #unit 



S.SQ 

,KEY [num-expr] ^=str-expr 
SAME KEY 



str-var 



Reads data from specified rejcord in MIDAS file on unit. Data is read 
into str-var . If READ KEY is specified, the key value is read into 
str-var . Num-expr and str- expr are the key nunbers and values, 
respectively, of the primary or secondary key. SEQ reads next 
sequential record. SAME KEIY returns datun only if next key matches 
current one. 



READ LINE #uhit,; sfcr-var 



Accepts entire line of text (including commas and colons) as one data 
item and puts it in str-var . ;^ads from a record in a file previously 
opened on unit . When the staterient has been executed, the internal 
record pointer automatically moves to the next record. 
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n£itti> if\jun.i,f vat— ±|, . . .veil.— 11 



Forces program to read a new record from the file previously opened on 
unit , var-1 through var-n are values to be read from current record. 
READ accepts value of the first variable in the record to which pointer 
is positioned. Pointer automatically moves to the next record after 
indicated values have been read. 



READ * #unit, var-l[; .. .var-n] 



^ signals program to continue reading data in current record before new 
one is read, var-1 through var-n are values to be read from current 
record and subsequent records, as necessary to satisfy variables 
listed. 



REM string 



Indicates remark to reader; ignored by system. Exclanation point (!) 
is substituted for REM v\*ien comments are added to executable 
statanents. 



REMOVE #unit [, KEY[num-expri - str-exprl + 



Deletes specified key fron MIDAS file. If primary key, num-expr = 0, 
is specified, data associated with key are removed also. Multiple keys 
may be deleted with one statement line; + indicates key specification 
may be repeated one or more times. 
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RiPtACE #unit SEG X BY SEG y 



Deletes file referenced by indicated segment (SEG x) on segment 
directory opened on indicated unit. Pointer at SEG y (segment y) is 
moved to segment x; old pointer at SEG y is 2eroed. 



RESxa^ 



# 
$ 



Instructs program to reuse list of data items beginning with first item 
in lov«st nunbered EATA statement. Numeric data items are reused by 
specifying #; string items, by $. Both nuneric and string items are 
reused if neither symbol is specified. RESTCRE must precede READ 
statement indicating data items to be reused. 



RETIBN- 



Causes control to be returned frcm GOSLB subroutine, 
in a program, exactly one RET'UItN must be executed. 



For every GOSLB 



BESpap #unit-l [,unit-2,,..unit-n] 



Repositions record pointer to top of file on specified unit or units. 
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REWIND #unit [,KEY num-expr] 



Rewinds pointer to beginning of MIDAS file opened on unit, at column 
specified by KEY num-expr . If num-expr= or is unspecified, pointer is 
positioned to primary key (default) . 



-SS©B-- 



Causes termination of program execution. Returns message: STOP AT 
LINE lin-num. 



Wtmh-^$mit, str-expr 



Writes string expression, str-expr , to current MIDAS file open on unit. 
Beware of changing keys with UPDATE if keys are being stored in record. 
BASICV does not monitor record composition and is not aware of changes 
made to key fields within a record. UPDATE is not equivalent to a 
REMOVE followed by an ADD. 



t^ITE" Iwiit , ., iteni-lf . . . iterti-n] 



Writes data, string or nixneric, specified by iton^l through J^tenwi, 
(string or numeric variables) , into the current record or output device 
opened on unit . If no values are specified, a blank line appears in 
the output. If a sequential file is closed after WRITE statement, all 
subsequent records in file are truncated. 
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WRITE #unit USING format-string, item-li;. ..itera-nl 

OR 
WRITE LBING format-string, #unit, itan-l[,. . .iton-n] 



Generates formatted output, determined by format characters in format- 
string^, including tabs, spaces, and column headircfs. Output is written 
to current record or output device opened on unit, item-1 through 
^'^^">~" sre nuneric or string variables or expressions. See Tables 
15-2, 15-3 for format characters. If itans are separated by colons 
instead of commas, they are pr:.nted one space apart rather than tabbed 
to the next print zone. Semicolons as separators cause itans to be 
printed with no intervening characters or spaces. 
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APPENDIX A 
SAMPLE PROGRAMS 

SAMPLE PROGRAMS 

BASIC/VM's flexible control structure and unique string handling 
capabilities make it easily adaptable to many applications. The three 
sample programs presented in this appendix utilize most of the features 
discussed earlier in the manual. The first program enables you to plot 
and print out a gra0i. The second can be used to test math skills, and 
the third performs simple text formatting. 

S ample Pogram 1; 

GRAPHICS PROGRAM 

100 ! GRAFH-DRWING PROGRAM 

110 ! 

120 ! GRAPH PROGRAM 

130 ! 

140 ! SET UP ARRAYS 

150 DIM C(2) ! C(l) = # OF HORIZ CHAR, C(2) = # VERT CHAR 

160 DIM M(2) ! M(l) = X MIN, M(2) = X MAX 

170 DIM N(2) ! N{1) = Y MIN, N(2) = Y MAX 

180 DIM P (120,120) ! POINT ARRAY, P(I,J) = 1 IF POINT IS DEFINED 

190 DIM X(100) ! X VALUES 

200 DIM Y(i00) ! Y VALUES 

210 ! 

220 DEF FNB(P$) 

230 FNB = VAL (LEFT (P$, INDEX (P$,' ')-!)) 

240 P? = RIGHr(P$,INEEX(P$,' ') +1) 

250 FNEND 

260 ! 

270 PRINT 'TYPE INPUT FILE NAl^E. ' 

280 INPUT F$ 

290 DEFINE READ FILE #1 = F$, ASC 

300 ! 

310 ON END #1 GOTO 400 

320 Z = 

330 FOR 1=1 STEP 1 WHILE Z = 

340 READ #1, X$ 

350 X? = CVr$$(X$,24) + ' ' 

3b0 X(I) = FNB(X$) 

370 Y(I) = FNB(X$) 

380 NEXT I 

390 ! 

400 N = I - 1 

410 PRINT 'DO AUTO SCALING?' 

420 INPUT A? 

430 I 

440 PRINT 'TYPE (# OF HORIZONTAL CHAR. , # OF VERTICAL CHAR. ) ' 

450 INPUT C(l), C(2) 
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460 IF AS = 'YES' THEN DO 




470 M(l) = X(l) 




480 M(2) = X(l) 




490 N(l) = Y(l) 




500 N(2) = Y(l) 




510 FOR I = 2 TO N 




520 IF X(I) > M(2) THEN M(2) 


= X{I) 


530 IF X(I) < M{1) THEN M(l) 


= X(I) 


540 IF Y (I ) > N (2 ) THEN N (2 ) 


= Y(I) 


550 IFY(I) < N(l) THEN N(l) 


= Y(I) 


560 NEXT I 




570 DOEND 




580 ELSE DO ! MANUAL SCALING 




590 PRINT 'TYPE MIN X, MAX X ' 




600 INPUT M(1),M{2) 




610 PRINT 'TYPE MIN Y, MAX Y' 




620 INPUT N(l), N(2) 




630 DOEND 




640 ! 




550 1 SET SCAI£ FACTORS 




660 K = (C(l) - 1)/(M(2) - M(l)) ! 


X SCALE FACTOR 


670 L = (C(2) - 1)/(N(2) -N(l)) 1 


Y SCALE FACTOR 


680 A = (M(2) - M(1)*C(1))/(M(2) - 


M(l)) 


690 B = (N(2) - N(1)*C(2))/(N(2) - 


N(l)) 


700 MAT P = ZER ! CF.RAR POINT ARRAY 


710 ! 




720 FOR I = 1 TO N ! FILL POINT ARRAY 


730 R = INT(K*X(I) f A + .5) 




740 S = INT(L*Y(I) + B + .5) 




750 IF R>0 AND R<=C(1) AND S>0 


AND S<=C(2) THEN P{R,S) 


760 NEXT I 




770 ! 




780 ! PRINT THE GRAPH 




790 ! 




800 FOR J = C(2) TO 1 STEP -1 




810 X$ = " ! BIANK OUT THE LINE BUFFER 


820 FOR I = 1 TO C(l) 




830 IF P(I,J) = 1 THEN X§ = 


x$ + '*• 


840 IF P(I,J) = THEN X$ = 


X$ + ' ■ 


850 NEXT I 




860 PRINT 'I':X$ 




870 NEXT J 




880 X$ = " 




890 FOR I = 1 TO C (1 ) + 2 




900 X$ = X$ + ■-' 




910 NEXr I 




920 FRINT X$ 




930 END 




>TYPE XXX 




3 4 




1 2 




2 2 




3 3 
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b 5 
8 5 

>RUN 

GRAPH FRI, JAN 05 iy79 Ib:b5:b4 



TYPE INPUT FILE NAME. 

i xxx 

DO AUrO SCALING? 

!YES 

TYPE (# OF HORIZONTAL CHAR., # OF VERTICAL CHAR.) 

1 30,10 

J * * 

I 

I 

I * 

I 

I 

I * 

I 

I 

I * * 
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Sample Program 2: 



MATH DRILL PROGRAM 

100 ! MATH DRILL PROGRA^l 

101 ! 

110 DIM S$(3) 

120 S$(l) = '+• ! INITIALIZE SYMBOL ARRAY 

130 S$(2) = '-' 

140 S$(3) = 'X' 

141 i 

150 ! DEFINE FUNCTION TO GENERATE RANDOM OPERANDS. 

160 DEF FNA(I,J) = INT (I *;RND (0 ) + J) 

161 ! 

170 R = ! R -> # ANSWERS CORRECT 

180 miNT "HELLO, WHO AI^ YOU?' 

190 INPUT N$ 

200 PRINT 'OK, ':N$: ' I H^VE SQ^E MATH PROBLEMS FCR YOU.' 

210 PRINT 'WHICH TYPE »■- PROBLEMS WOULD YOU LIKE?' 

220 PRINT '1. ADDITION' 

230 PRINT '2. SUBTRACTKU' 

240 PRINT '3. MULTIPLICATICW' 

250 PRINT '4. MIXED' 

260 PRINT 

270 PRINT 'TYPE 1, 2, 3, OR. 4' 

280 INPUT T ! T IS PROBLEM CLASS 

290 PRINT 'HOW MANY SECONDS SHALL I GIVE YOU TO ANSWER EACH PROBLEM?' 

300 INPUT U 

310 S = VAL (SUB (TIMES, 7, 9)) ! SEED RANDOM # GEN 

320 S = RND(-1*S) 

330 PRINT 'READY?' 

340 INPUT A$ 

350 IF A$ = 'NO' THEN STOP 

360 ! 

370 ! BEGIN MAJOR LOOP 

380 ! 

381 Z = 

390 FOR W = 1 STEP 1 WHILE Z = 

400 ! W IS PRCBLEM # AND Z IS EXIT FLAG. 

402 PRINT CHAR (140) 

410 IF T = 1 THEN V = 1 ! V IS INDEX INTO SYMBOL ARRAY S$ 

420 IF T = 2 THEN V = 2 

430 IF T = 3 THEN V = 3 

440 IF T = 4 THEN V = FNA(3,1) 

450 B = FNA(9,3) 

460 IF V = 1 THEN DO 

470 A = FNA(9,3) 

480 Q = A + B 

490 DOEND 

500 IF V = 2 THEN DO 

510 A = FNA(B,1) 

520 Q = B - A 
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b30 DOEND 

540 IF V = 3 THEN DO 

550 A = FNA(9,3) 

560 Q = A*B 

570 DOEND 

580 PRINT B:S$(V):A: '=': 

590 ENTER U,M,C 

500 IF C <> Q THEN DO 

bl0 IF M >= THEN IX) 

620 PRINT 'WRONG ': N$: '.' 

630 DOEND 

640 ELSE DO 

650 PRINT 'YOU TOOK TOO LONG, TRY AGAIN. ' 

650 DOEND 

670 IF V = 1 THEN Pi^INT B:S$ (V) :A: '=' :A4e 

680 IF V = 2 THEM PIUNT B:S$(V):A: • = ":B-A 

590 IF V = 3 THEN PI^INT B:S§(V):A: ■ = ':B*A 

700 DOEND 

710 EtSE DO 

720 D = INT(3*RND(0) + 1) 

730 IF D = 1 THEN TOINT 'RIGHT, ' :N$: '. ' 

740 IF D = 2 THEN PRINT 'VERY GOOD. ' 

750 IF D = 3 THEN PRINT N$: ', YOU GOT IT!' 

760 IF D > 3 THEN PRINT 'CORRECT! ' 

770 PRINT 'YOU TOOK ' :M: 'SECONDS TO GET THE ANSVER. 

780 R = R + 1 

790 DOEND 

800 PRINT 'MORE?' 

810 INPUT A$ 

820 IF A$ = 'NO' THEN Z = 1 

830 NEXT W 

840 ! 

850 ! END OF MAJOR LOOP 

860 ! 

870 PRINT 'YOU GOT ':R: 'OUT OF ' :W-1: 'CCRRECT. ' 

880 PRINT 'GOOD BYE.' 

890 END 

>RUN 



MATH FRI, JAN 05 1979 15:57:31 



HELLO, WHO ARE YOU? 

1 LAURA 

OK, LAURA I RAVE SCME MATH TOCBLEMS FOR YOU. 

WHICH TYPE OF TOOBLEMS WOULD YOU LIKE? 

1. ADDITION 

2. SUBTRACTION 

3. MULTIPLICATION 

4. MIXED 

TYPE 1, 2, 3, CR 4 

HOW MANY SECONDS SRZ^LL I GIVE YOU TO ANSWER EACH PROBLEM? 
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!10 

READY? 
!YES 

6 + 5 = 12^ 
VERY GOOD. 

YOU TOOK 2 SECCNDS TO GET THE ANSWER. 
MORE? 
lYES 



rHE ANSWER. 



4+6 


= 10 


LAURA 


, YOU GOT IT! 


YOU TOOK 1 SECOND TO GET : 


MCRE? 




•YES 




3X6 


= 12 


WRONG 


LAURA . 


3X6 


= 18 


MORE? 




!YES 




7 + 4 


= y0 


WRONG 


LAURA . 


7 + 4 


= 11 


MORE? 




•NO 




YOU GOT 2 OUT OF 4 CORRECT 


GOOD BYE. 


>QUIT 
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Sample Program 3; 

TEXT HANDLING WITH STRING FUNCTIOJS 

100 REM FNA$ - SIMPLE TEXT JUSTIFICATION, lii-20-78 

110 

120 REM CALLING SEQUEtCE: 

130 REJ-1 STRING = FNA$ (INPUT_STRING, OUTPUT STRING LENGTH) 

140 

150 

160 DEF FNA$(X$, L) 

170 L2 = LEN (X?) 

180 N = ! N = # OF WCytD DELIMITERS (SPACES) 

190 

200 FOR 12 = 1 TO L2 ! COUNT # OF WO^DS 

210 IF SUB(X$, 12) = " ■ THEN N = N + 1 "IF SPACE, INCREMENT 

220 NEXT 12 

230 

240 IF N = THEN DO 

250 A2$ = X$ + SPA(L - L2) ! HANDLE ONE WORD CASE 

260 DO END 

270 ELSE DO 

280 SI = INT( (L-L2)/N ) + 1 ! # SPACES TO PUT BEWIXT EACH WORD 

290 S2 = (L-L2) MOD N ! # RESIDUAL SPACES 

300 A2$ = " ! CLEAR OUT RESULT 

310 

320 FOR 12 = 1 TO L2 ! LOOP THRU INPUr STRING 

330 IF SUB(X$, 12) <> ' ' THEN DO ! HIT SPACE? 

340 A2$ = A2$ + SUB(X$, 12) 1 NO, NORMAL CHARACTER 

350 DO END 

360 ELSE DO 

370 A2$ = A2$ + SPA (SI) ! HIT SPACE, PUT IN SI SPACES. 

380 IF S2 <> THEN DO ! ANY RESIDUAL SPACES? 

390 A2$ = A2$ + • ' 1 YES, PUT A SPACE HERE. 

400 S2 = S2 - 1 

410 DO END 

420 EX) END 

430 NEXT 12 

440 DO END 

450 FNA$ = A2$ 

460 FN END 

470 REM 

480 REM 

490 REM — This is the main driver for the text justification system 

500 REM 

510 PRINT 'Very dumb text justification system' 

520 PRINT 

530 INPUT 'Enter input file: ', Fl$ 

540 DEFINE READ FILE #1 = Fl$ 

550 INPUT 'Margin: ',L9 

560 ON END #1 GOrO 740 

570 PRINT 

580 PRINT 
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590 S$ = '■ ! Clear out text input accumulator 

600 

610 IF L£N (S$) - 1 > L9 THEN CO ! Have we filled up enough input text ? 

620 S$ = SUB(S$, 1, LEN(S$)-1) ! Yes, ranove the blank on the end 

630 FOR J = L9 STEP (-1) UNTIL SUB(S$,J) = ' ' ! Find the last wrd 

640 NEXT J 

650 PRINT FNA$ (SUB (S$, 1, J-1), L9) ! Call the justification routine 

660 S? = SUB(S$, J+1, LE3SI(S$)) + ■ ' ! Pickup unprocessed input 

670 DO END ! And continue. 

680 ELSE DO ! Come here v*ien we are ready to do another read. 

690 READ LINE #1, Fl$ ! Get a line of input text. 

700 S$ = S$ + CVT$$(F1$, 152) + ' ' ! Concat with the unprocessed text 

710 DO END ! And continue. 

720 GOTO 610 ! Try again, folks. 

730 REM — End of file processing 

740 PRINT S$ ! Print out unprocessed text (at bottom of paragraph) 

750 PRINT 

760 STOP 

yrYFE XXX 

Four score and seven years ago, our fathers brought forth 

to this continent a new nation, 

conceived in liberty, and dedicated to the proposition that 

all men are created equal. 

> RUN 

JUST WED, JAN 10 1979 09:48:12 



Very dumb text justification system 

Enter input file: XXX 
Margin: 35 



Four score and seven years ago, 
our fathers brought forth to this 
continent a new nation, conceived 
in liberty, and dedicated tc the 
proposition that all men are 
created equal. 

STOP AT LINE 760 
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ASCII CHARACTER SET 



The following is a list of the ASCII character set with the 
corresponding decimal equivalent and the meaning of each character. 



Decimal 






Value 


ASCII 




(with parity on) 


Character 


Explanation 


128 




Null or fill character 


129 




Start of heading 


130 




Start of text 


131 




End of text 


132 




End of transmission 


133 




Enquiry 


134 




Acknowledge 


135 




Bell 


136 




Backspace 


137 




Horizontal tab 


138 




Line feed 


139 




Vertical tab 


140 




Form feed 


141 




Carriage return 


142 




Shift out 


143 




Shift in 


144 




Data link escape 


145 




Device control 1 


146 




Device control 2 


147 




Device control 3 


148 




Device control 4 


149 




Negative acknowledge 


150 




Synchronous idle 


151 




End of transmission block 


152 




Cancel 


153 




End of medium 


154 




Substitute 


155 




Escape 


156 




File separator 


157 




Group separator 


158 




Record separator 


159 




Unit separator 


160 




Space 


161 


! 


Exclamation psint 


162 


II 


Double quotation mark 


163 


# 


Number or pound sign 


164 


$ 


Dollar sign , 


165 


% 


Percent sign 


166 


£c 


Ampersand 


167 


1 


Apostrophe 
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168 


( 


Opening (left) parenthesis 


169 


) 


Closing (right) parenthesis 


170 


* 


Asterisk 


171 


+ 


Plus 


172 


1 


Comma 


173 


- 


Hyphen or minus 


174 


• 


Period or decimal point 


175 


/ 


Forward slant 


176 





Zero 


177 


1 


One 


178 


2 


Two 


179 


3 


Three 


180 


4 


Four 


181 


5 


Five 


182 


6 


Six 


183 


7 


Seven 


184 


8 


Eight 


185 


9 


Nine 


186 


J 


Colon 


187 


/ 


Semicolon 


188 


< 


Left angle bracket (less than) 


189 


= 


Equal sign 


190 


> 


Right angle bracket (greater than) 


191 


p 


Question mark 


192 


h 


Commercial at sign 


193 


A 


(193 through 218 are upper case characters) 


194 


B 




195 


C 




196 


D 




197 


E 




198 


F 




199 


G 




200 


H 




201 


I 




202 


J 




203 


K 




204 


L 




205 


M 




206 


N 




207 







208 


P 




209 


Q 




210 


R 




211 


S 




212 


T 




213 


U 




214 


V 




215 


w 




215 


X 




217 


Y 




218 


Z 




219 


[ 


Opening bracket 


220 


\ 


Bac<ward slant 
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221 


] 


222 


" 


223 




224 


■^ 


225 


a 


226 


b 


227 


c 


228 


d 


229 


e 


230 


f 


231 


g 


232 


h 


233 


i 


234 


J 


235 


k 


236 


1 


237 


m 


238 


n 


239 


o 


240 


P 


241 


q 


242 


r 


243 


s 


244 


t 


245 


u 


246 


V 


247 


w 


248 


X 


249 


y 


250 


z 


251 


{ 


252 


1 


253 


} 


254 


"^ 


255 
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Closing bracket 
Circumflex or up arrow 
Underscore or backarrow 
Grave accent 
(225 through 250 are lower case characters) 



Opening (left) brace 
Vertical line 
Closing (right) brace 
Tilde 
Delete 
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APPENDIX C 
RUN-TIME ERROR CODES 



Code Number Message 

1 GOSUBS NESTED TOO DEEP 

2 RETURN WITHOUT GOSUB 

3 EXCESS SUBSCRIPT 

4 TOO FEW SUBSCRIPrS 

5 SUBSCRIPr OUT OF RANGE 

6 ARRAY TOO LARGE 

7 STORAGE SPACE EXCEECED 

8 BAD I-O UNIT 

9 BAD FILE RKCRD SIZE 

10 DA RECCRD SIZE ERROR 

11 UNDEFINED 1-0 UNIT 

12 WRITE ON READ ONLY FILE 

13 END OF DATA 

14 END OF FILE 

15 FILE IN USE 

16 NO UFD ATTACHED 
^17 DISK FULL 

18 NO RIGHT TO FILE 

19 ILLEGAL FILE NAME 

20 FILE 1-0 ERRCR 

21 FILE NOT FOUND 

22 INPUT DATA ERRCR 

23 VkL ARG NOT NIMERIC 

24 BAD LINE NUMBER IN ASC LN FILE 

25 ILLEGAL OPERATION ON SEGMENT DIRECTORY 

26 READ AFTER WRITE ON SEQUENTIAL FILE 

27 ILLEGAL 0PERATIC9M ON BINARY FILE 

28 UNDEFINED MATRIX 

29 ILLEGAL SEG DIR REFERENCE 

30 ILLEGAL FILE TYPE FCR POSITION 

31 ILLEGAL POSITION RETCRD NUMBER 

32 WRITE IBING TO NCN-ASCII FILE 

33 roiNT USING STOING IN NLMERIC FORMAT 

34 PRINT USING NUMERIC IN STRING FORMAT 

35 PRINT LBING FORMAT WITH NO EDIT FIELDS 

36 BAD MARGIN SPECIFIER 

37 MATRIX NOT SQUARE 

38 MISMATCHED DMENSIONS 

39 OPERAND AND RESULT MUST BE DISTINCT 

40 2 DIMENSIONAL MATRIX REQUIRED 

41 INV MATRIX IS SINGULAR 

42 MOD - SECCND ARGUMENT ZERO 

43 EXPONENTIATION - BAD ARGIWENTS 

44 SIN, COS - ARGUMENT RANGE ERRCR 

45 TAN - OVERFLCW 
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46 ASN, ACS - ARGUMENT RANGE ERRCR 

47 EXP - OVERFLOW 

48 EXP - ARGUMENT TOO LARGE 

49 LOG - ARGUME3W < = 

50 SORT - ARGUMENT < 

51 EXPONENT OVEIRFLOW, UNDERFLOW 

52 DIVISION BY ZERO 

53 STORE FLQ\TING ERROR 

54 REAL TO INTEGER CONVERSIOJ ERRCR 

55 ON GOTO-GCSLB OVERRANGE ERROR 
55 RECORD NOT FOUND 

57 RECCED LOCKED 

58 RECCRD NOT LOCKED 

59 KEY ALREADY EXISTS 

60 SEGMENT FILE IN USE 

61 INCONSISTENT RECORD LENGTH 

62 RECORD FILE FULL 

63 KEY FILE FULL 

64 IMPROPER FILE TYPE 

65 PRIMARY KEY NOT SUPPLIED 

66 ILLEGAL OPERATION ON UNIT 

67 FATAL MIDAS ERROR 

68 RAISED TO OR A NEGATIVE POWER 

69 CONSTANT ON LEFT SIDE OF ASSIGNMENT STATEMENT 

70 MIDAS CCNCURREN::Y ERRCR 



REV. 



Pm3058 ADDITIONAL miMOS FEATURES 



APPENDIX D 
ADDITIONAL PRIMOS FEATURES 



This appendix contains a glossary of useful PRIMOS tems, an 
introduction to the system EDITOR, an introduction to command files, 
and a brief discussion of the TERM command, with which terminal 
characteristics can be modified. 



GLOSSARY CF PRIME CONCEPTS AND COMVENTIONS 

The following is a glossary of concepts and conventions basic to Prime 
computers, the PRIMOS operating system, and the file system. 

• abbreviation of FRIMOS commands 

Only internal FRIMOS commands may be abbreviated. 

• binary file 

A translation of source file generated by a language translator 
(BASICV, COBOL, FTN, RPG) . 

• byte 

8 bits; 1 ASCII character. 

• CPU 

Central Processor Unit (the Prime computer proper as distinct from 
peripheral devices or main memory) . 

• current directory 

A temporary working directory explained in the discussion on Home vs 
Current Directory later in this section. 

• directory 

A file directory; a special kind of file containing a list of files 
and/or other directories, alorg with information on their 
characteristics and location. MFDs, UFDs, and subdirectories 
(sub-UFDs) are all directories. (Also see segment directory.) 

• directory name 

The file name of a directory. 
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• external command 

A miMOS command existing as a runfile in the command directory 
(O1DNC0) . It is invoked by nane, and executes in user address space. 
External commands print GO when starting, and cannot be abbreviated. 

• file 

An organized collection of information stored on a disk (or a 
peripheral storage mediim such as tape). Each file has an identifying 
label called a filename. 

• filename 

A sequence of 32 or fewer characters v>4iich names a file or a directory. 
Within any directory, each filename is unique. Director y names and a 
filename may be combined into a pathname . Most commands accept a 
pathname wherever a filename is required. 

Filenames may contain only the following characters: 

A-Z, 0-9, __#$-. * 

The first character of a filename must not be numeric. On some devices 
underscore (_) prints as backarrow (<-) . 

• filename conventions 

Prefixes indicate various typ)es of files. These conventions are 
established by the compilers and loaders, or by common use, and not by 
PRIMOS itself. 

B__filename Binary (Object) file 

C__filename Coninand input file 

L__filename Listing file; 

M_filename Load map file 

0__filename Command output file 

filename Source file or text file 

*filename SAVED (Executable) R-mode runfile 

#filename SAVED (Ex©::utable) V-mode runfile 
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• file-unit 

A nunber between 1 and 63 ('77) assigned as a pseudonym to each open 
file by FRIMOS. This number may be given in place of a filename in 
certain commands, such as CLOSE. FRIMOS-level internal commands 
require octal values. Each user may have up to 16 file units open at 
the same time. Certain commands or activities use particular unit 
numbers by default: 



FRIMCG assigned units Octal Decimal 



INPUT, SLIST 


1 


1 


LISTING 


2 


2 


BINARY 


3 


3 


AVAIL 


5 


5 


COMINPUT 


6 


6 


SEG's loadmap 


13 


11 


cop40urPLrr 


77 


63 


EDITOR 


1,2 


1,2 


SORT 


1-4 


1-4 


RUNOFF 


1-3 


1-3 



• file protection keys 
See keys, file protection. 

• home directory 

The user's main working directory, initially the login directory. A 
different directory may be selected with the ATTACH command. 

• identity 

The addressing mode plus its associated repertoire of computer 
instructions. Programs compiled in 32R or 64R mode execute in the 
R-identity; programs compiled in 64V mode execute in the V-identity. 
R-identity and V-identity are also called R-mode and V-mode. 

• internal command 

A command that executes in FRIMOS address space. Does not overwrite 
the user manory image. Internal commands can be abbreviated. See 
"abbreviation of FRIMOS commands". 
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• key, file protection 

Specifies file protection, as in the FROTEC command. 

No access 

1 Read 

2 Write 

3 Read/Write 

4 Delete and truncate 

5 Delete, truncate and recid 

6 Delete, truncate and write 

7 All rights 

• LDEV 

Logical disk device nunber as printed by the command STATUS DISKS. 
(See Idisk.) 

• Idisk 

A parameter to be replaced by the logical unit number (octal) of a disk 
volime. It is determined v\*ien the disk is brought up by a STARTUP or 
ADDISK command. Printed as LDEV by STATUS DISKS. 

• logical disk 

A disk volume that has been assigned a logical disk nunber by the 
operator or during systan startup. 

• MFD 

The Master File Directory. A special directory that contains the names 
of the UFDs on a particular disk or partition. There is one MFD for 
each logical disk. 

• nodename 

Name of system on a network; assigned v\hen local FRIMOS system is 
built or configured. 

• nimber representations 



xxxxx 


Decimal 


' xxxxx 


Octal 


$xxxxx 


Hexadecimal 



• object file 
See binary file 
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• open 

Active state of a file-unit. A command or program opens a file-unit in 
order to read or write it. 

• output stream 

Output from the computer that would usually be printed at a terminal 
during conmand execution, but v^iich is written to a file if COMOUTPUT 
command was given. 

• packnane 

See volume-name. 

• page 

A block of 1024 16-bit words within a segment (512 words on Prime 300). 

• partition 

A portion [or all] of a multihead disk pack. Each partition is treated 
by PRIMOS as a separate piiysical device. Partitions are an integral 
nunber of heads in size, offset an even number of heads from the first 
head. A volune occupies a jjartition, and a "partition of a disk" and a 
"volume of files" are actually the same thing. 

• pathname 

A multi-part name v^hich uniquely specifies a particular file (or 
directory) within a file system tree. A pathname (also called 
treename) gives a path from the disk volume, through directory and 
subdirectories, to a particular file or directory. See the discussion 
on Pathnam es in this section. 

• mEV 

Physical disk unit number as printed by STATUS DISKS. (See pdisk.) 

• pdisk 

A parameter to be replaced by a physical disk unit number. Needed only 
for operator coitmands. 

• phantom user 

A process running independently of a terminal, under the control of a 
command file. 
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• SEG 

Prime's segmentation utility. 

• segment 

A 65,536-word block of address space. 

• segment directory 

A special form of directory used in direct-access file operations. Not 
to be confused with directory, v*ich means "file directory". 

• segno 
Jjegment nunber. 

• source file 

A file containing programming language statements in the format 
required by the appropriate canpiler or assembler. 

• subdirectory 

A directory that is in a LFD or another o subdirectory. 

• sub-UFD 

Same as subdirectory. 

• treename 

A synonym for pathname. 

• UFD 

A User File Directory, one of the Directories listed in the MFD of a 
yolune. It may be used as a LOGIN name. 

• unit 

See file-unit. 

• vol ume 

A self-sufficient unit of disk storage, including an MFD, a disk record 
availability table, and associated files and directories. A volune may 
occupy a complete disk pack or be a partition within a multi-head disk 
pack. 
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• volume-name 

A sequence of 6 or fewer characters labeling a volume. The name is 
assigned during formatting (by MAKE). The STATUS DISKS coitmand uses 
this name in its DISK column to identify the disk. 

• word 

As a unit of address space, two bytes or 16 bits. 



SETTING TEPMINAL CHARACTERISTICS 

Terminal characteristics may be set with the TERM command. These 
characteristics remain in effect until you reset than or until ysu log 
out. Ihe ccHtimonly used TERM options are listed below. Typing TERM 
with no options returns the full list of TERM options available. The 
format is: 

TERM options 
The options are: 



-ERASE character 



-KILL character 



-XOFF 



-NO)«DFF 
DISPLAY 



Sets user's choice of erase character in place 
of the default, ". 

Sets user's choice of kill character in place 
of default, ?. 

Enables X-OFF/X-ON feature, v^^iich allows 
programs to halt without returning to FRIMOS 
command level. Programs may be resumed at 
point of halt by typing CONTROL -Q. Programs 
are halted by typing CCNTROL-S. Also sets 
terminal to full duplex (default value.) 

Disables X-OFF/X-ON feature (default) . 

Returns list of currently set TERM characters. 
Also displays current EUplex, Break and 
X-ONA-OFF status. 
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EDITOR 



Prime's text EDITCR can be used to create and edit text files and 
programs. It has two modes, INPUT and EDIT. Either blank line 
followed by a carriage return, or tw CR's in a row, switches the 
EDITOR from one mode to the other. EDITOR is handy for preparing 
dociments, reports, letters and programs, and for properly formatting 
them via the RUNOFF feature of FRIMOS. It is also useful for creating 
command files, discussed below. A complete description of all EDITOR 
and RUNOFF features can be found in the New User's Guide To EDITOR and 
RUNOFF. 

Input Mode 

INPUT mode is used for creatine new files or programs or for adding 
more text to an existing file. It accepts lines of text that are 
entered into the system by a CF., as are all PRIMOS commands. To create 
a new file or program with the EDITOR, type: 

ED 

This automaticaly puts the EDIIOR into INPUT mode. 

Edit Mode 

EDIT mode is used to modify the contents of a file or program file. 
There are over fifty commands available for use in EDIT mode. A good 
summary of these commands is provided in the FRIMOS Programmer's 
Companion. These commands allow you to move lines from one point to 
another in a file, to delete lines, to load in other files or parts of 
files, to format a file according to your particular needs (using 
RUNOFF commands) and to make line-specific or general changes in 
vocabulary, terms, etc. For BASIC/VM programmers, this is extranely 
handy when changing program variables, vHnen moving lines of code, and 
when combining several programs. 

lb modify an existing file, type: 

ED filename 

The EDITOR opens the file, makes a copy of it in the current working 
directory, and switches into EDIT mode. All changes made to this 
'work' file will not be incorporated into the disk copy until the file 
is 'FILEd', or saved, with the :?ILE command of the EDITOR. Separate 
copies of the 'work' file and the disk file may be maintained by 
FILEing the 'work' file under a name of its own. For example, to save 
an edited file under a nams other than the original, type FILE, 
followed by a new filename: 

FILE new-filename 
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Summary of Editor Coirmands 



Conrnand 
APPEND 

BOTTOM 

CHANGE/stRl/str2/ 
DELETE [n] 
pUNLOAD 

FILE 

FIND strirvg 

WIODIFY 

INSERT newline 

LOAD filename 

NEXT [n] 

OVERLAY string 

POINT n 
PRINT [n] 
QUIT 

RETYPE string 

TOP 



Function 

Attaches specified text to end of current 
line. 

Positions pointer to bottom of file. 

Replaces string l(strl) with string 2(str2). 

Deletes n lines including the current line. 

Copies specified # of lines from work file to 
another file and deletes those lines from the 
work file. 

Saves current work file to disk. Takes 
filename argument if current work file is not 
to overwrite disk file copy. 

Finds first line below current containing 
given string. 

String-oriented editing routine for individual 
lines. 

Inserts newline following current line, 
newl ine becomes current line. 

Copies contents of f ilen^e into work file 
under current line. 

Moves the pointer n lines. Positive or 
negative values accepted. 

Overlays given string over current line, 
starting in column one. 

Positions the pointer to line number n. 

Prints n lines. 

Quits out of an EDITOR session to roiMOS 
command level . 

Deletes current line and replaces it with 
st r ing . 

Repositions pointer to top of file. 
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UNLOAD Similcir to DUNLOAD but does not delete 

indicated lines from WDrk file. 

WHERE Prints current line number. 

Using th e EDITOR For BASIC Programs 

The EDITOR can easily be used to write BASIC programs, even though 
BASICA^M has its own 'Editor' facility. The advantage of the PRIMOS 
EDITOR is the freedom to work and make changes without having to worry 
about line nunbers and other BASIC constraints. Programs should be 
typed in upper-case letters, as only upper-case commands and statements 
are accepted by the BASIC compiler. Also, all syntax rules, as 
detailed in Section 4, should be followed. After a program has been 
FILEd, it can be nunbered for use in the BASIC subsystem by using the 
PRIMOS NIMBER command. Full details on this command are found in "The 
Reference Guide to PRIMOS Commands. 

Ttie NUMBER command requests the name of the file to be numbered or re- 
numbered, the name of the output file, vJt\ich must differ from the 
original, the starting number and the increment value. For example, to 
nunber an Editor-created progrem starting with line number 10 and 
continuing in increments of 10, do the following: 



OK, s list ex 

GO 

INPUT A 

INPUT B 

PRINT A*B 

H=A/B 

IF H<0 THEN 10 

PRINT H 

END 

OK, number 

00 

INTREEmME, OUTTREEI^F^E, START, INCR, 

ex ex3 10 10 

OK, slist 8x3 

GO ~ 

10 INPUT A 

20 INPUT B 

30 PRINT A*B 

40 H=A/B 

50 IF H<0 THEN 10 

60 PRINT H 

70 END 
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COMMAND INPUT FILES (CCMINPUT) 



COniNPUT I pathname [funit] 

-CONTINUE 
-END 
-PAUSE 
-START 
-TTY 

The COMINPUT conmand causes FRMOS to take commands and data input from 
a specified file rather than from the user's terminal. Command files 
are usually created with the EDITOR. 

filename is the name of the file from vAiich input is to be read. 

funit is the FRIMOS file unit number on which the input file is 

to be opened. If omitted. File Unit 6 is assumed. 

options Specify control flow. -TTY tells FRMOS resume accepting 

input from the terminal. A command file should end with 
COMINPUT -TTY. The other options and their effects are 
discussed in Reference Guide, FRIMOS Commands, FDR 31 08. 

Note 

The CCMINPUT command must be specified with at 
least one parameter. If CO is specified with a 
null parameter the message: NOT FOUND is printed 
at the terminal. Note also that the inclusion of 
CLOSE ALL in a COMINPUT file closes the file and 
causes the error message COMINP FILE EOF to be 
displayed. 

Command input files are especially useful for repetitive processes such 
as compiling and loading a series of programs, building libraries, 
running production, and changing erase and kill characters at LOGIN 
time. BASIC/VM has its own COMINP conmand, which is similar in 
function to COMINPUT. The format and syntax are slightly different, as 
explained in Section 6. 

Comments can be included in a command file at FRIMOS level by preceding 
each contnent with the characters /*. The end of each comment is 
delimited by the characters /*. 

COMMAND OUTPUT FILES (COMOUFPUT) 

The COMOUTPUT command tells FRIMOS to send a copy of all terminal input 
and output to a specified file (called a 'comout' file) , as well as (or 
instead of) to the user's terminal. The format is: 
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COvlOUTPUT [treename] [option-1] . . , [option-n] 

The options are described below. Logical combinations of options are 
{Jermissable. 



-CONTINUE Continues command output to a file. With the -CONTINUE 
option, subsequent terminal output is appended to the file 
specified by filen.ame. 



-END 



Stops command output to a file and closes the command 
output file unit. 



-NTTY Turns off the terminal output, i.e., does not print or 

display responses to command lines, including the prompt 
OK,. Once -NTTY has been specified, terminal output is not 
turned on until -T.?Y is specified in a subsequent COMOUTPUT 
comnand. 

-PAUSE Stops command output to filename. However, the command 

output file, filencjme, remains open. 

-TTY turns on the terminal output. 

Command output (comoutput) files are useful when the user wants to keep 
a record of terminal transactions. FRIMOS opens File Unit 17 and 
writes all command input and output responses to the file specified by 
filename. 

Examples 

OK, CCMO OUTPUT 
GO 

• • ■ 

'mis command line arranges for subsequent terminal output to be written 
to the file named OUTPUT. Contrands are echoed, and responses continue 
to be displayed at the terminal. The file named OUTPUT is overwritten 
if it already exists. 



OK, CCMO -NTTY 

Terminal output continues to the file named OUTPUT, but no terminal 
output is printed or displayed at the terminal. 

• « • 

OK, CGMO -END 
The file named OUTPUT is closed. Furthermore, since -TTY was not 
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specified following a ^^JTTY, terminal output will not be printed or 
displayed en til the command line: 

COMO -TTY 

is issued 

• • • 

OK, COIO OUTPUT -C -P 

The file named OUTPUT is opened and positioned to end-of-file, but no 
terminal output is sent to the file. 

Remember that command output files are not closed by CLOSE ALL; they 
must be closed explicitly by COMO -END, CLOSE unit-number or CLOSE 
filename. 
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APPENDIX E 

ADVANCED FILE HANDLING 

CONTENTS 

The information contained in this appendix is intended to supplement 
that presented in Section 8. File handling operations such as READs 
and WRITES are covered in more detail, with special attention given to 
the default ASCII file type. Other information concerns access methods 
and file properties, altering the record size in DA and SA files, and 
truncation patterns observed in each file type. This information may 
be useful in deciding which file types to use in various data handling 
situations. 

ACCESS METHODS 

Data files can be accessed by one of four basic methods: Direct 
access. Sequential access, MIDAS and Segment directory (SEGDIR) access. 
Ihe direct and sequential access methods are detailed below. MIDAS and 
SEGDIR protocols are more complex. Ptore information on these access 
methods can be found in the Subroutine Reference Guide, and in 
Reference Guide, MIDAS. 

Sequent ial Access Method 

In sequential access, files are treated as a series of variable-length 
records. In sequential access, a file pointer is maintained to 
indicate the "current record" (the one that is involved in the current 
I/O operation). After each access, the pointer is moved to the next 
sequential record, which then becomes the current record. Thus, in 
order to reach the end of the file, each record in the file, beginning 
with the first, must be accessed in turn. It is not possible to skip 
records or back up to a previous record in sequential access files, 
except to return to the top of the file. This is known as "rewinding" 
the file pointer. 

Sequential files are space-efficient since the records are only as long 
as the data they contain. However, random access to a particular 
record is time-consuming, since all the records between the current 
position and the desired position must be read. 

Di rect Access ftethod (DAM) 

Files structured for direct access require an additional set of 

pointers Oiich point to each record in the file. These pointers are 

automatically defined and maintained by the systan, so the user needn't 
worry about them. 
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Direct access files must have fixed-length records. The record length 
may be increased or decreased frcsn the default size of 60 words. The 
record length information is then stored in the header of the file for 
use by the file pointer. 

Data retrieval is extremely flexible in direct access files. Any 
record in the file can be randomly positioned to by number. Records 
are numbered consecutively from the top of the file to the bottom, 
beginning with number 1. As data are added to the file, the number of 
records increases as necessary. Fbsitioning is done internally by the 
system and involves counting the nimber of records (and therefore the 
number of characters) v*iich must be bypassed before the desired record 
is reached. For example, if the record size is set to 40 words, (80 
characters) and data from the third record are to be read, the pointer 
'calculates' that 160 characters must be skipped before the third 
record can be read. When 160 characters have been bypassed, the 
pointer will be positioned to the beginning of the third record. The 
importance of fixed-length records in direct access is readily 
apparent . 



EATA STORAGE PATTERI^ 

The following pages describe how data are stored in each file type. 

D ata Stor age in ASCII and Binary Files 

All files in BASICAM can be generally classified according to file 
type and access method. File type refers to the manner in v*iich a file 
stores data. This is known as data storage. There are two major data 
storage methods: ASCII and Binary. 

The main difference between Ai3CII and binary files is the way in which 
they code data for disk storage. The same datum written to both an 
ASCII and binary file is converted to a different format in each type 
of file. Subsequently, when displayed at the terminal, the data in the 
files will not appear identical. 

ASCII: In ASCII files, all data, both numeric and string, are 
represented in ASCII character rode, packed two characters per 16-bit 
word. Numeric values entered in decimal character format are converted 
to floating point internal format. When a file is read, the data 
values must be re-converted. String values are returned as the string 
characters vAiich correspond to the stored ASCII codes. Numeric values 
are converted fran floating point format to decimal representation, and 
are formatted according to any print format conventions specified, 
e.g., decimal paints, dollar signs, etc. 

The main feature of ASCII files is their ease of inspection, i.e., they 
can be SLISTed, or TYPEd at zhe terminal. They store data just like 
terminal output. Thus, their r^scord storage patterns can be easily 
monitored for data integrity. 
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Binary ; String data are stored in binary files as they are in ASCII 
files, i.e., in ASCII code. Numeric data are stored in internal 
machine format, i.e., four-word floating-point representation. There 
is no conversion to or from ASCII representation, so complete data 
accuracy is retained. 

However, binary files cannot be accurately inspected through SLIST, 
TYPE or ED (the PRIMOS editor) . Their storage patterns cannot be 
easily assessed by the user. 

Data Storage in Each F ile Type 

Within the general ASCII and binary file groups, files are further 
subdivided according to properties like record type, (variable or 
fixed- length) and access methods. In addition to these previously 
mentioned properties, distinctions can be made on the basis of 
intra- record data structure. 

During file access, information is retrieved from a file one record at 
a time. Usually, specific data itans must be retrieved from a record 
during a file READ. Therefore, there must be some way of internally 
marking where one item ends and the next one begins within a record. 
This is known as intra- record data structure. 

Below is a description of the major features of each type of file, with 
the exception of SEGDIR and MIDAS features v^iich are dealt with later 
in this section. These descriptions are intended to aid you in 
selecting the files best suited to your particular data storage and 
access requirements. 

ASC files; are the default file type in BASIC/VM. They store data 
exactly like terminal output. Semi-colons, commas and colons force 
data to be written to an ASC file exactly as they would be output by a 
similar PRINT statement. Each item written to the file is separated 
from the next datum by the appropriate number of spaces forced by the 
indicated delimiter. Thus, spaces are the actual data delimiters in 
the intra-record structure of ASC files. 

10 DEFINE FILE #1= 'SPACE' 

15 READ A,B,C 

20 DATA 20,21,22 

25 WRITE #1, A,B,C 

30 WRITE #1, A;B;C 

35 WRITE #1, A:B:C 

40 CLOSE #1 

45 END 

>TYPE SPACE 

2^ 21 22 

202122 

20 21 22 
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ASC files have variable-lengtJ-i records. The default size of 60 words 
can be decreased or increased as necessary. In cases where items 
larger than 60 words are being stored, record-size should be enlarged 
appropriately. 

A SCSEP files : are ASCII sequential files that use commas instead of 

spaces as internal data markers. Data written to an ASCSEP file can be 

read back in the same form as written. For example, if the following 
values are written to an ASCSEP file: 

12,13,14 

They will be stored and read bark as indicated: 

>TYPE SEP 
12,13,14,15, 
>READ #1,A 
>PRINT A 
12 

It should be noted that string items containing commas will be 
fragmented when read back from the file. Commas, both verbatim and 
inserted, are interpreted as data delimiters. For example, if the val 
ue '$12,000' is written to an ASCSEP file it is stored as: 

$12,000, 

When read back, following occurs: 

READ#1, A$ 
PRINT A$ 
$12 

The data has obviously been fragmented. This problem can be ranedied 
by using an alternate form of READ, READLINE. READLINE accepts the 
entire contents of one ASCII record, including canmias, semicolons, 
colons and spaces, as one datutr. 

ASCSEP files are sequentially accessed, but they have fixed-length 
records. Unlike ASCII direi^t access files, vAiich also have 
fixed-length records (discussed below) , ASCSEP file records are not 
blank-padded on the right to fill out any space not occupied by data. 
Instead, the physical end of the records marked by a carriage return 
(CR) . The delimiters used to affect record structure in ASC default 
files have no effect in ASCSEP files. Regardless of whether a WRITE 
statement is terminated by a comma, semicolon, colon or blank, the next 
sequential WRITE statement will write data to the next record. 
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A3CLN files; are ASCII sequential files with variable length records 
and inserted line-numbers. Conunas are inserted as delimiters in ASCLN 
files, just as they are in ASCSEP files. Every record added to an 
ASCLN file is preceded by a line-number. Records are nunbered in 
incranents of 10, beginning with 10. When values are read back from 
the file, line numbers are stripped away. 

The LIN# (unit) function (See Section 10) can be used to determine the 
actual line number at v*iich the current I/O operation is being 
performed. 



>DEFINE FILE #1 = 'LINES', ASCLN 



>WRITE 


#1, 200 


,300,400 


>WRITE 


#1, 34. 


56 


>REWIND #1 




>TYPE 


LINES 




10 


200,300, 


400, 


20 


34.56, 




>READ 


#1, A 




>PRINT 


LIN#(1) 




10 






>PRINT 


A 




200 






x:lose 


#1 





ASCU^ files are the only data files which may be edited at BASICV 
command level. Like a BASIC/VM program, they can be called to the 
foreground, LISTed, edited with BASICV commands and resequenced. ASCLN 
files are convenient for data that are continually being updated or 
otherwise modified. 

ASCDA files : are ASCII direct access files. They have fixed-length 
records which are blank-padded to completely fill any record space not 
filled with data. Commas are inserted as data delimiters just as in 
ASCSEP files. A special file containing pointers to each record in the 
ASCDA file is maintained by the system for use in random access to data 
records. 

The intra-record data structure is similar to that of an ASCSEP file. 
Extra spaces and 'blips' are usually output at the terminal due to the 
blank-padding factor. For example: 

>10 DEFINE FILE #3 = 'DIR', ASCDA 

>20 WRITE #3, 12,13,14 

>30 WRITE #3, 123.45 

>RUNNH 

STOP AT LINE 30 

>TYPE DIR 

12,13,14, 

123.45, 
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As in ASCLN files, the LIN # (unit) function can be used to detennine 
the exact location of a record pointer in a direct access file. 

BIN and BINCA files: of both types have fixed-length records. String 
data are stored as in ASCII files, i.e., in ASCII code; numeric data 
are stored in internal machine formats, i.e., four-word floating-point 
representation, ensuring ccxnplete data accuracy. Program execution is 
also expedited because less translation time is required during numeric 
data access. 

Although BIN and BINDA files lx>th have fixed-length records, BIN files 
are accessed sequentially, v^ile BINDA files are accessed by the direct 
access method. 

Data storage patterns in binary files cannot be accurately inspected at 
the terminal. If a binary file is TYPED or LISTED, the data may or may 
not be recognizable. Despite the inspection inconvenience, binary 
files are extremely useful for scientific canputations requirirq 
complete precision and data accuracy. 

Any portion of a record not filled with data is zeroed out rather than 
blank-filled. 

Writing to ASC Files 

ASC files have special properties v*iich distinguish them from others. 
Some of the properties v\^ich affect data written to ASC files are 
discussed below. 

In ASC files only, successive WRITE statements can be forced to 
continue writing data to the same record until the record is filled. A 
line of data written to an ASC file can contain colon, comma, or 
sanicolon delimiters between data itans. Data will be stored exactly 
as if they had been output by a PRINT statement. Each delimiter 
affects data storage differently: 



• a comma - causes item to be placed in next print zone. 

• a semicolon - causes next item to be placed in next character 
position. 

• a colon - causes next item to be placed one character position 
from the preceding item. 
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The following program writes data to an ASC file utilizing each 
delimiter. Each line output after TYPE ASCII represents the contents 
of a logical record. User input is underlined. 



10 DEFINE FILE #1= 


='ASCII' 


20 READ A,B,C,D,E, 


rF,G 


25 DATA 22,23,24,; 


25,26,27,28 


30 WRITE 


#1,A,B, 




35 WRITE 


#1,C:D: 




40 WRITE 


#1,E,F; 




45 WRITE 


#1,G 




50 WRITE 


#1,A:B: 




55 WRITE 


#1,C:D: 




60 WRITE 


#1,E:F: 




65 WRITE 


#1,G 




70 WRITE 


#1,A,B, 




75 WRITE 


#1, C:D: 




80 WRITE 


#1,E;F; 




85 WRITE 


#1,G 




>TYPE ASCII 




22 




23 


8 







22 23 24 25 26 27 28 
22 23 



24 25 25 



24 25 262728 



272 



ACCOMODATING LARGE DATA ITEMS 

Altering Record Size For SAM Files 

Increasing the record size in a default ASCII file allows data items 
larger than 60 words to be stored in one record. If a string item in 
excess of 120 characters is written to a file with default record 
length, as much of the item as possible is written to the current 
record; the rest is written to the next record. Records are added as 
needed to accomodate this item. 

>DEFINE FILE #1='T1' ,ASC, 4 
>WRITE #1, ' HARRY G. DOF^K' 
> TYPE Tl 
HARRY G. 
D(^K 



If the combined length of several numeric items being written to an ASC 
file exceeds the set record length, the way they will be stored depends 
on their individual lengths and on the delimiters v\^ich separate them. 
This example illustrates several vieys in which large data items can be 
stored by varying the delimiters. Note that the record size has been 
set at 6 words. 

>10 DEFINE FILE #1 = 'PLAIN ',6 
>20 READ A,B,C 
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>30 EftTA 12,13456,7800000 

>40 WRITE #1,A,B,C 

>45 WRITE #1,A;B;C 

>50 WRITE #1,A:B:C 

>55 WRITE #1,A 

>60 CLOSE #1 

>65 END 

>RUNNH 

> TYPE PLAIN 

12 

13456 

7800000 

1213456 

7800000 

12 13456 

7800000 

12 

Data items will not be truncated v^ien written to an ASC file, even 
though the results of a file READ may create this impression. 

ASCLN files: have the same properties as ASC default files in regard 
to storage patterns. In each ASCLN file record, four character 
positions are occupied by the inserted line numbers. This should be 
kept in mind when setting the record size for this type of file. 
Overlarge data items are treated in the same manner as discussed above. 

Example: 

>DEFINE FILE #1 = 'SMALL', ASCL N, 5 
> WRITE #1, 'TOTALLY OUTRAGEOUS' 
> TYPE SMALL 

10 TOTA 

20 LLY 

30 OUTR 

40 AGEO 

50 US, 

A SCSEP files : differ from ASC and ASCLN files both in structure and in 
data storage. Records in an ASCSEP file are fixed-length. Commas are 
automatically inserted as data delimiters. Each one takes up one 
character position in the record. If a data item too large to fit in a 
single record is written to an ASCSEP file, it will be truncated. 

>DEFINE FILE #1 = 'SI', .^CSEP, 5 
>WRITE #1, 'TOTALLY OUTRAGEOUS' 



> TYPE SI 
TOTALLY OU 

If several numeric items are written to the same file in a single WRITE 
statanent , the length of each item relative to the record size will 
determine whether it will be stored intact or truncated. If the 
current record can accomodate only one item, the next iten in the list 
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will be written to the next record. If it is too large to fit into 
this record, it will be truncated. 

Delimiters occurring at the end of a WRITE statanent have no effect on 
subsequent WRITE statanents as they do in ASC files. 

BIN files; maintain data quite differently from ASCII files. Although 
the exact nature of intra-record data storage is not readily known, the 
following example indicates that data items larger than the set record 
size are not truncated. Instead, they are stored in a manner v*iich 
allows entire data items to be retrieved with a single READ, even if 
the datum exceeds the set record length. 

>DEFINE FILE #1 = 'BINARY ', BIN, 5 
> WRITE #1,12345 678910.32 
>TYPE BINARY 

__ [{J=" 
>RB/JIND #1. 
>READ TI7~ A 
>PRINT A 
12345678910.32 
x:lose #1 

Altering Record Size in D^ Files 

The method used to retrieve data from a direct access file requires all 
the records in the file to have the same length. When records are 
being added to the file, the record size should be kept in mind. If 
data items written to an ASCDA record contain fewer characters than the 
maximum set by the record size, the data are padded internally with 
blanks until the record is entirely filled. In BINDA files, unused 
record space is zero filled. If, on the other hand, data in excess of 
the currently set record size are inadvertently written to a DA file, 
one of two things can occur: 



• If the current record is empty, and the datum exceeds the 
record size, it will be truncated. 

• If a series of items, e.g., A,B,C$, are included in a single 
WRITE statement, and C$ will not fit entirely into the 
remainder of the record, the pointer moves to the next 
sequential record and C$ is stored there. If C$ is larger than 
a single record, it will be truncated. 

Example : 

10 DEFINE FILE #1 = 'TRZ ' , ASCI:A,8 

20 WRITE #1,1234, 5678, 'MAGNIFICENT' 

30 WRITE #1, 'I AM EIGHTEEN CHAR', 123,456 

40 REWIND #1 

>TYPE TRZ 

1234,5678, 
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MAOJIFICENT, 

I AM EIGHTEEN C, 

123,456, 

W riting Blank Lines to a File 

If no variables or values are specified with WRITE, a blank record will 
be added to the file. This causes a blank line to occur in the output 
v^en the file is TYPEd. 

Example: 

> DEFINE FILE # 1 = 'BLl' 
>DEFINE FILE #2 = 'BL2', ^SCSEP 



>WRITE 


#1, 


12 


>WRITE 


#2, 


12 


>WRITE 


#1 




>WRITE 


#2 




>WRITE 


#1, 


13 


>WRITE 


#2, 


13 


>TYPE BLl 




12 






13 






>TYPE BL2 




12, 






13, 






Truncating 


a File 



Writing data to a record that already contains data results in the over 
writing of the old data. If the file is CLOSEd inmediately subsequent 
to the overwrite, the file will be truncated. The record just written 
to thus becomes the last record in the file. 

Example: 

>TYPE ASCS EP 

TWAS THE NIGHT BEFORE CHRliSTMAS, 

AND ALL THROUGH THE HOUSE, 

NOT A CREATURE WAS STIRRING, 

NOT EVEN A MOUSE., 

>DEFINE FILE #1 = 'ASCSEP', ASCSEP 

> READ #1, A$ 

>PRINT A$ 

twas the night before christmas 
>write #1, 'and santa was broke' 
x:lose #1 



>TYPE ASCSEP 

TWAS THE NIGHT BEFORE CFKISTMAS, 

AND SANTA WAS BROKE, 
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Beyond this point, the original lines in the file have now been 
overwritten or truncated, as shown above. 



READING ASCII FILES 

READing Defaul t ASCII Files 

The special properties of ASCII default files affect the results of 
file READS in a manner worth explaining in some detail. These READ 
features are not applicable to other file types. 

READ results vary with the data delimiters within each record, as 
explained earlier. The READ pointer looks for commas as end of data 
markers in all file types. Thus, it does not consider the ASC spacing 
delimiters to be delimiters. Because of the properties of ASC files, 
they are the only ones adversely affected by this feature. 

If several nuneric items are written to a file with various delimiters, 
as shown below: 

10 DEFINE FILE #1= 'SPACE' 

15 READ A,B,C 

20 DATA 20,21,22 

25 WRITE #1, A,B,C 

30 WRITE #1, A;B;C 

35 WRITE #1, A:B:C 

40 CLOSE #1 - . 

45 END 

>RUNNH 

>TYPE SPACE 

20 21 22 

202122 

20 21 22 
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The following may result when soveral READs are performed; 

>D EFINE READ FILE #1 = 'S PACE' 
>READ #1, A 
>FRINT A 



202122 

> READ #1,B 

> PRINT B 

202122 

>READ #1,A,B,C 

END OF FILE AT LINE 

>R EWIND #1 

>READ #1,A,B,C 

>PRINT_A^^^ 

202122 202122 202122 

>READ #1,A 

END OF FILE AT LINE 



READing With Numeric and String Variables 

When ASC data items are READ into a string variable, e.g., READ #1, A$, 
all the values in the record, spaces included, are returned as one 
datum. The first conma reached marks the end of the datum; however if 
there are no verbatim commas in the data, a single string READ will 
return the entire record as a single datun. For example, if the values 
12, 13 and 14 are written to an ASC file record, and nuneric and string 
READS are done, the results are as follows: 

>DEFINE FILE #1 = 'JUNK' 



>WRITE #1, 12,13,14 




>REWIND #1 




>READ #1,A 




>PRINT A 




121314 




>REWIND #1 




>READ #1, A$ 




READ^fTTA^ 




>FRINT A$ 




12 


13 


>TYPE JUNK 




12 


13 


> 





14 
14 



All spaces are discarded in a numeric READ because they are not 
considered numeric in value. Therefore, all numeric items are 
concatenated v*ien READ into a numeric variable. 



A record containing both string and numeric values with no coitmas 
between data itans, (commas can be inserted by writing them to the file 
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like this: 12,' ,' ,13. . .) can be read in its entirety with a single 
string variable, but not with a single numeric variable. 



Example: 

>DEFINE FILE #1 = 'ASCII', ASC 



>WRITE #1, 'SUGAR', 


12.00 


>WRITE #1, 'FLOUR', 


5.00: 'COFFEE' 


>REWIND #1 




>TYPE ASCII 




SUGAR 


12 


FLOUR 


5 COFFEE 


>READ #1,A 




INPUT EATA ERROR AT 


LINE 


>READ #1,A$ 




>PRINT A$ 




FLOUR 


5 COFFEE 


>REWIND #1 




>READ #1,A$,B 




INPUT D^TA ERROR AT 


LINE 


>REWIND #1 




>READ #1,A$,B$ 




>PRINT A$ 




SUGAR 


12 


>PRINT B$ 




FLOUR 


5 COFFEE 



The INPUT EATA ERRCR message indicates that a string value can not be 
read into the numeric variable specified. 

READing From Other Sequential Files 

Values from a record are READ into the given nuneric or string 
variable(s) specified with the READ statement. For sequential files, 
the following READ properties are observed: 

• If a record contains numeric data only, READ #unit, A returns 
the first numeric datum in the record, as delimited by the 
first comma. 

• If a record contains string data only, READ #unit, A$ reads 
the first string value as delimited by the first cortma in the 
record. If a string item itself contains a comma, it will be 
truncated at the position where the comma occurs. 

• If the record contains both string and nuneric data, READ 
#unit, A will return a numeric item only if it appears first 
in the record: READ #unit, A$ will return either numeric or 
string values, dependirg on which occurs first in the record. 

• String data can only be read into string variables, .e.g, READ 
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#1, A$. Numeric data can be read into either numeric or 
string variables, e.g., either READ #1, A or READ #1,A$ will 
return a numeric value. 



Example : 

>DEFINE FILE #1 = 'ASCSEP', ASCSEP 



>WRITE #1, 12 


>REWIND #1 


>READ #1, A 


>PRINT A 


11 


>REWIND #1 


>READ #1, A$ 


>PRINT A$ 


12 


>WRITE #1, 'STRINGY' 


>REWIND #1 


>READ #1,A,B$ 


>PRINT A, B$ 


12 


>REWIND #1 


>READ #1,A,B 


INPUT EATA ERRCR AT ] 


>REWIND #1 


>READ #1,A 


>READ #1,8$ 


>FRINT~B$ 


STOINGY 


READing ASCLN Files 



STRINGY 



Because ASCLN files insert line nunbers in front of each record, it 14s# 
easy to tell where the fila pointer is positioned during any I/O 
operation. The sys tan-provided function, LIN #(unit), can be used to 
to display the current record number. 



>DEFINE FILE #1 = 'LINEl', ASCLN 

>WRITE #1/HI ! ' 

>WRITE""il,'HaAr 

>WRITE #1, 'ARE' 

>WRITE #1, 'YODT' 

>REWIND #1 

>TYPE LINEl 

10 HI!, 

20 HOW, 

30 ARE, 

40 YOU!, 
>READ #1,A$ 
>PRINT LrN#(l) 
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10 

>PRINT A$ 

HI! 

> READ #1,B$,C$,D$ 

>PRINT LIN#(1) 

40 

>PRINT A$:B$;C$;D$ 

HI! HOW ARE YOU! 

Surmiary of READs on Sequential Files 

The following example shows how the properties of sequential files 
influence the results of simple file READs. 

10 ON ERROR #1 GOTO 270 
20 DEFINE FILE #1 = 'ASC 
30 DEFINE FILE #2 = 'ASCSEP' , ASCSEP 
40 DEFINE FILE #3 = 'ASCLN', ASCLN 
50 DEFINE FILE #4 = 'BINSAM' , BIN 
60 READ A,B,C$ 
70 EATA 123.45,48, '$100,000' 
80 FOR I = 1 TO 4 
90 WRITE #1, A,B,C$ 
100 REWIND #1 
110 NEXT ,1 
120 FOR N = 1 TO 4 

130 PRINT 'NUMERIC READ FCR FILE ON UNIT #': N 
.140 PRINT 
150 READ #N, A 
160 PRINT A 
170 REWIND m 

180 PRINT 'STRING READ FCR FILE ON UNIT #': N 
190 PRINT 
200 READ #N, A$ 
210 PRINT A$ 
220 PRINT 
230 REWIND #N 
240 NEXT N 
250 CLOSE #1,2,3,4 
260 END 

270 PRINT ERR${ERR) 
280 GOTO 170 

>TYPE ASC 

123745 48 $100,000 

>TYPE ASCSEP 

123. 45,48, $100, 000, 

>TYPE ASCLN '■ 

10 123.45,48,-$100,000, 
>TYPE BINSAM 

{s3333'?100,000>. 
>RUNNH 
NUMERIC READ FCR FILE ON UNIT # 1 
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INPUT EATA ERRCP 

STOING READ FOR FILE ON UNIT # 1 

123.45 48 $100 

NUMERIC READ FOR FILE ON UNIT # 2 

123.45 

STRING READ FCR FILE ON UNIT # 2 

123.45 

NUMERIC READ FCR FILE ON UNIT # 3 

123.45 

STRING READ FCR FILE ON UbdT # 3 

123.45 

NUMERIC READ FCR FILE ON UNIT # 4 

123.45 

STRING READ FCR FILE ON UMT # 4 

_Js3333'$100,000 

The INPUT DATA ERROR message appears because a numeric READ was 
attempted on an ASC file record containing both numeric and string 
data. Since this was expected, an error trap mechanism was included in 
the program. The ON ERROR statement (line 10) is further described 
below. 

Note that a string READ of a binary file produces strange results. The 
numeric data values are not converted to decimal form when read with a 
string variable. 



READ* With Default ASC Files 

In default ASCII files, the READ* statement is most useful when records 
contain only string values. The variables for READing thus must be 
carefully chosen to avoid INPUT EATA ERROR messages. This requires 
some familiarity with the data being READ or otherwise manipulated. 

Ihe following example EEFINEs and WRITES string data to several 

sequential files. Both types of READs, with and without stars (*) , are 

performed to afford some comparison between the two forms of READs on 
various SAM files. 

Example: 

10 DEFINE FILE #1= 'ASC*' 
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'RED', 'WHITE', 'BLUE 



',' PURPLE' 



20 DEFINE FILE #2 = 'SEP*' , ASCSEP 

30 DEFINE FILE #3 = 'LN*' , ASCLN 

40 DEFINE FILE #4 = 'B:[N*' , BIN 

50 REWIND #1,2,3,4 

60 READ A$,B$,C$,D$ 

70 DATA 

80 FRIMT 'FIRST RE?^D WITHOUT *' 

85 PRINT 

95 FOR N=l TO 4 

100 WRITE #N,A$,B$ 

105 WRITE #N,C$,D$ 

110 NEXT N 

120 REWIND #1,2,3,4 

135 FOR N= 1 TO 4 

136 PRINT 'THIS IS FILE ON UNIT #': N 

137 PRINT 'BEGIN READ WITHOUT *' 
140 READ #N,A$ 

145 FRINT A$ 
150 PRINT 
155 READ #N,B$ 
160 PRINT B$ 
162 FRINT 

165 RElA?IND #N 

166 PRINT 'NOW READ WITH *' 
170 READ * #N, A$ 

175 raiNT A$ 
178 PRINT 
180 READ * #N,B$ 
185 PRINT B$ 
190 raiNT 

200 REWIND #N 

201 PRINT 'END OF READ ON UNIT #':N 

202 PRINT 
205 NEXT N 

220 CLOSE #1,2,3,4 

230 PRINT 'END OF TEST' 

240 END 

>RUNNH 

FIRST READ WITHOUT * 



THIS IS FILE ON UNIT # 1 

BEGIN READ WITHOUT * 

RED WHITE 



BLUE 



PURPLE 



NOW READ WITH * 

RED WHITE 

BLUE PURPLE 

END OF READ ON UNIT # 1 
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THIS IS FILE ON UNIT # 2 
BEGIN READ WITHOUT * 
RED 

BLUE 

NCW READ WITH * 
RED 

WHITE 

END OF READ ON UNIT # 2 

THIS IS FILE ON UNIT # 3 
BEGIN READ WITHOUT * 
RED 

BLUE 

NCW READ WITH * 
RED 

WHITE 

END OF READ ON UNIT # 3 

THIS IS FILE ON UNIT # 4 
BEC;iN READ WITHOUT * 
RED 

BLUE 

NOW READ WITH * 
RED 

WHITE 

END OF READ ON UNIT # 4 

END OF TEST 
>TYPE ASC* 



RED 


WHITE 


BLUE 


PLRPLE 


>TYPE SEP* 




RED,WHITE, 




BLUE, PURPLE, 




>TYPE DM* 





10 RED, WHITE, 
20 BLUE, PURPLE, 

>TYPE BIN* 

REDWHITEBLUEPURPLE> 
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